@tonyclaw/agent-inspector 2.0.0 → 2.0.2

package/src/knowledge/openclawClient.ts

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import type { KnowledgeCandidate, KnowledgeSearchResponse, OpenClawMemoryPayload } from "./types";
 import { KnowledgeSearchResponseSchema, KnowledgeSearchResultSchema } from "./types";
+import { isOpenClawGatewayConfigured, searchOpenClawGateway } from "./openclawGatewayClient";
+import { isOpenClawFileBridgeConfigured, writeCandidateToOpenClawMemory } from "./openclawMarkdown";
 import { redactCandidate } from "./redactor";
 
 const OpenClawWriteResponseSchema = z.object({
@@ -18,12 +20,16 @@ export type PromoteResult =
       error: string;
     };
 
-function getEndpoint(): string | null {
+function getLegacyEndpoint(): string | null {
   const endpoint = process.env["OPENCLAW_MEMORY_URL"] ?? process.env["OPENCLAW_API_URL"];
   if (endpoint === undefined || endpoint.trim() === "") return null;
   return endpoint.trim();
 }
 
+function isLegacyBackendConfigured(): boolean {
+  return getLegacyEndpoint() !== null;
+}
+
 function buildMemoryUrl(endpoint: string): string {
   return endpoint.endsWith("/memories") ? endpoint : `${endpoint.replace(/\/$/, "")}/memories`;
 }
@@ -61,11 +67,21 @@ export function buildOpenClawPayload(candidate: KnowledgeCandidate): OpenClawMem
 }
 
 export async function promoteToOpenClaw(candidate: KnowledgeCandidate): Promise<PromoteResult> {
-  const endpoint = getEndpoint();
+  if (isOpenClawFileBridgeConfigured()) {
+    const result = await writeCandidateToOpenClawMemory(candidate);
+    if (result.success) {
+      return { success: true, memoryId: result.memoryId };
+    }
+    return { success: false, error: result.error };
+  }
+
+  const endpoint = getLegacyEndpoint();
   if (endpoint === null) {
     return {
       success: false,
-      error: "OpenClaw memory backend is not configured. Set OPENCLAW_MEMORY_URL.",
+      error:
+        "OpenClaw memory backend is not configured. Set OPENCLAW_WORKSPACE_DIR " +
+        "for file-backed memory or OPENCLAW_MEMORY_URL for a legacy HTTP backend.",
     };
   }
 
@@ -91,11 +107,20 @@ export async function searchOpenClaw(
   query: string,
   project?: string,
 ): Promise<KnowledgeSearchResponse> {
-  const endpoint = getEndpoint();
+  if (isOpenClawGatewayConfigured()) {
+    return await searchOpenClawGateway(query, project);
+  }
+
+  const endpoint = getLegacyEndpoint();
   if (endpoint === null) {
+    const workspaceHint = isOpenClawFileBridgeConfigured()
+      ? " OPENCLAW_WORKSPACE_DIR is configured for writes, but search requires OPENCLAW_GATEWAY_URL."
+      : "";
     return {
       results: [],
-      warning: "OpenClaw memory backend is not configured. Set OPENCLAW_MEMORY_URL.",
+      warning:
+        "OpenClaw search backend is not configured. Set OPENCLAW_GATEWAY_URL " +
+        `or OPENCLAW_MEMORY_URL.${workspaceHint}`,
     };
   }
 
@@ -116,3 +141,7 @@ export async function searchOpenClaw(
   }
   return { results: [], warning: "OpenClaw search returned an unparseable response." };
 }
+
+export function isOpenClawPromotionConfigured(): boolean {
+  return isOpenClawFileBridgeConfigured() || isLegacyBackendConfigured();
+}

package/src/knowledge/openclawGatewayClient.ts

@@ -0,0 +1,237 @@
+import { z } from "zod";
+import type { KnowledgeSearchResponse, KnowledgeSearchResult } from "./types";
+
+const OpenClawGatewayErrorSchema = z
+  .object({
+    type: z.string().optional(),
+    message: z.string().optional(),
+  })
+  .passthrough();
+
+const OpenClawGatewayInvokeResponseSchema = z
+  .object({
+    ok: z.boolean().optional(),
+    result: z.unknown().optional(),
+    error: OpenClawGatewayErrorSchema.optional(),
+  })
+  .passthrough();
+
+const OpenClawGatewayContentItemSchema = z
+  .object({
+    type: z.string().optional(),
+    text: z.string().optional(),
+  })
+  .passthrough();
+
+const OpenClawMemoryHitSchema = z
+  .object({
+    id: z.string().optional(),
+    path: z.string().optional(),
+    title: z.string().optional(),
+    kind: z.string().optional(),
+    corpus: z.string().optional(),
+    score: z.number().nullable().optional(),
+    snippet: z.string().optional(),
+    content: z.string().optional(),
+    source: z.string().nullable().optional(),
+    startLine: z.number().optional(),
+    endLine: z.number().optional(),
+  })
+  .passthrough();
+
+const OpenClawToolResultDetailsSchema = z
+  .object({
+    results: z.array(OpenClawMemoryHitSchema).optional(),
+  })
+  .passthrough();
+
+const OpenClawToolResultSchema = z
+  .object({
+    results: z.array(OpenClawMemoryHitSchema).optional(),
+    details: OpenClawToolResultDetailsSchema.optional(),
+    content: z.array(OpenClawGatewayContentItemSchema).optional(),
+  })
+  .passthrough();
+
+type OpenClawMemoryHit = z.infer<typeof OpenClawMemoryHitSchema>;
+
+export function getOpenClawGatewayUrl(): string | null {
+  const value = process.env["OPENCLAW_GATEWAY_URL"];
+  if (value === undefined || value.trim() === "") {
+    return null;
+  }
+  return value.trim();
+}
+
+export function isOpenClawGatewayConfigured(): boolean {
+  return getOpenClawGatewayUrl() !== null;
+}
+
+function buildToolInvokeUrl(gatewayUrl: string): string {
+  return `${gatewayUrl.replace(/\/$/, "")}/tools/invoke`;
+}
+
+function getOpenClawSessionKey(): string {
+  const value = process.env["OPENCLAW_SESSION_KEY"];
+  return value === undefined || value.trim() === "" ? "main" : value.trim();
+}
+
+function getGatewayToken(): string | null {
+  const token =
+    process.env["OPENCLAW_GATEWAY_TOKEN"] ??
+    process.env["OPENCLAW_GATEWAY_PASSWORD"] ??
+    process.env["OPENCLAW_API_KEY"];
+  if (token === undefined || token.trim() === "") {
+    return null;
+  }
+  return token.trim();
+}
+
+function gatewayHeaders(): Headers {
+  const headers = new Headers({ "content-type": "application/json" });
+  const token = getGatewayToken();
+  if (token !== null) {
+    headers.set("authorization", `Bearer ${token}`);
+  }
+  return headers;
+}
+
+function buildSearchQuery(query: string, project?: string): string {
+  if (project === undefined || project === "") {
+    return query;
+  }
+  return `${query}\nProject: ${project}`;
+}
+
+function formatHitTitle(hit: OpenClawMemoryHit, index: number): string {
+  if (hit.title !== undefined && hit.title !== "") {
+    return hit.title;
+  }
+  if (hit.path !== undefined && hit.path !== "") {
+    return hit.path;
+  }
+  if (hit.id !== undefined && hit.id !== "") {
+    return hit.id;
+  }
+  return `OpenClaw memory result ${String(index + 1)}`;
+}
+
+function formatHitId(hit: OpenClawMemoryHit, index: number): string {
+  const base = hit.id ?? hit.path ?? `result-${String(index + 1)}`;
+  const start = hit.startLine === undefined ? "" : `:${String(hit.startLine)}`;
+  const end = hit.endLine === undefined ? "" : `-${String(hit.endLine)}`;
+  return `openclaw:${base}${start}${end}`;
+}
+
+function formatHitContent(hit: OpenClawMemoryHit): string {
+  if (hit.snippet !== undefined && hit.snippet !== "") {
+    return hit.snippet;
+  }
+  if (hit.content !== undefined && hit.content !== "") {
+    return hit.content;
+  }
+  return "";
+}
+
+function formatHitType(hit: OpenClawMemoryHit): string {
+  if (hit.kind !== undefined && hit.kind !== "") {
+    return hit.kind;
+  }
+  if (hit.corpus !== undefined && hit.corpus !== "") {
+    return hit.corpus;
+  }
+  return "openclaw-memory";
+}
+
+function mapGatewayHit(
+  hit: OpenClawMemoryHit,
+  index: number,
+  project?: string,
+): KnowledgeSearchResult {
+  return {
+    id: formatHitId(hit, index),
+    type: formatHitType(hit),
+    title: formatHitTitle(hit, index),
+    content: formatHitContent(hit),
+    score: hit.score ?? null,
+    source: hit.source ?? "openclaw",
+    project: project ?? null,
+    evidence: hit,
+  };
+}
+
+function extractGatewayHits(result: unknown): OpenClawMemoryHit[] | null {
+  const parsed = OpenClawToolResultSchema.safeParse(result);
+  if (!parsed.success) {
+    return null;
+  }
+  return parsed.data.details?.results ?? parsed.data.results ?? [];
+}
+
+function formatGatewayError(raw: unknown): string {
+  const parsed = OpenClawGatewayInvokeResponseSchema.safeParse(raw);
+  if (!parsed.success) {
+    return "OpenClaw Gateway returned an unparseable response.";
+  }
+  const message = parsed.data.error?.message;
+  if (message !== undefined && message !== "") {
+    return message;
+  }
+  return "OpenClaw Gateway tool invocation failed.";
+}
+
+export async function searchOpenClawGateway(
+  query: string,
+  project?: string,
+): Promise<KnowledgeSearchResponse> {
+  const gatewayUrl = getOpenClawGatewayUrl();
+  if (gatewayUrl === null) {
+    return {
+      results: [],
+      warning: "OpenClaw Gateway is not configured. Set OPENCLAW_GATEWAY_URL.",
+    };
+  }
+
+  const response = await fetch(buildToolInvokeUrl(gatewayUrl), {
+    method: "POST",
+    headers: gatewayHeaders(),
+    body: JSON.stringify({
+      tool: "memory_search",
+      args: {
+        query: buildSearchQuery(query, project),
+        maxResults: 10,
+        corpus: "all",
+      },
+      sessionKey: getOpenClawSessionKey(),
+    }),
+  });
+
+  const raw: unknown = await response.json().catch(() => null);
+  if (!response.ok) {
+    return {
+      results: [],
+      warning: `OpenClaw Gateway search failed with ${response.status}: ${formatGatewayError(raw)}`,
+    };
+  }
+
+  const parsed = OpenClawGatewayInvokeResponseSchema.safeParse(raw);
+  if (!parsed.success) {
+    return { results: [], warning: "OpenClaw Gateway returned an unparseable response." };
+  }
+  if (parsed.data.ok === false) {
+    return { results: [], warning: formatGatewayError(raw) };
+  }
+
+  const hits = extractGatewayHits(parsed.data.result);
+  if (hits === null) {
+    return {
+      results: [],
+      warning: "OpenClaw memory_search returned an unparseable tool result.",
+    };
+  }
+
+  return {
+    results: hits.map((hit, index) => mapGatewayHit(hit, index, project)),
+    warning: null,
+  };
+}

package/src/knowledge/openclawMarkdown.ts

@@ -0,0 +1,146 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { KnowledgeCandidate } from "./types";
+import { redactCandidate } from "./redactor";
+
+export type OpenClawFilePromotionResult =
+  | {
+      success: true;
+      memoryId: string;
+      relativePath: string;
+      absolutePath: string;
+    }
+  | {
+      success: false;
+      error: string;
+    };
+
+export function getOpenClawWorkspaceDir(): string | null {
+  const value = process.env["OPENCLAW_WORKSPACE_DIR"];
+  if (value === undefined || value.trim() === "") {
+    return null;
+  }
+  return value.trim();
+}
+
+export function isOpenClawFileBridgeConfigured(): boolean {
+  return getOpenClawWorkspaceDir() !== null;
+}
+
+function normalizeDatePrefix(value: string): string {
+  const date = value.slice(0, 10);
+  return /^\d{4}-\d{2}-\d{2}$/.test(date) ? date : "undated";
+}
+
+function normalizePathSegment(value: string, fallback: string): string {
+  const segment = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 96);
+  return segment === "" ? fallback : segment;
+}
+
+function formatNullable(value: string | null): string {
+  return value === null || value === "" ? "unknown" : value;
+}
+
+function formatList(values: string[]): string {
+  return values.length === 0 ? "none" : values.join(", ");
+}
+
+function buildEvidenceLink(candidate: KnowledgeCandidate): string {
+  return `agent-inspector:session:${candidate.sessionId}:candidate:${candidate.id}`;
+}
+
+export function buildOpenClawMemoryRelativePath(candidate: KnowledgeCandidate): string {
+  const date = normalizeDatePrefix(candidate.updatedAt);
+  const slug = normalizePathSegment(candidate.id, "candidate");
+  return path.join("memory", "agent-inspector", date, `${slug}.md`).replace(/\\/g, "/");
+}
+
+export function buildOpenClawMemoryMarkdown(candidate: KnowledgeCandidate): string {
+  const sanitized = redactCandidate(candidate);
+  return [
+    "# Agent Inspector Memory Candidate",
+    "",
+    "Layer: L3 memory candidate for OpenClaw L4 durable recall",
+    "Source: agent-inspector",
+    "",
+    "## Metadata",
+    "",
+    `- Type: ${sanitized.type}`,
+    `- Status: ${sanitized.status}`,
+    `- Project: ${formatNullable(sanitized.evidence.project)}`,
+    `- Session: ${sanitized.sessionId}`,
+    `- Log IDs: ${sanitized.logIds.join(", ")}`,
+    `- Models: ${formatList(sanitized.evidence.models)}`,
+    `- Tags: ${formatList(sanitized.tags)}`,
+    `- Created: ${sanitized.createdAt}`,
+    `- Updated: ${sanitized.updatedAt}`,
+    `- Evidence: ${buildEvidenceLink(sanitized)}`,
+    `- Redacted: ${String(sanitized.redaction.redacted)}`,
+    `- Redaction patterns: ${formatList(sanitized.redaction.patterns)}`,
+    "",
+    "## Durable Knowledge Candidate",
+    "",
+    sanitized.content,
+    "",
+    "## Recall Guidance",
+    "",
+    [
+      "- Treat this as reviewed Agent Inspector knowledge extracted from LLM interaction traces.",
+      "- Use the evidence id to return to Agent Inspector when raw proof is needed.",
+      "- Do not treat this file as raw logs; sensitive values were redacted before export.",
+    ].join("\n"),
+    "",
+  ].join("\n");
+}
+
+function resolveTargetPath(workspaceDir: string, relativePath: string): string | null {
+  const root = path.resolve(workspaceDir);
+  const target = path.resolve(root, relativePath);
+  const relative = path.relative(root, target);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    return null;
+  }
+  return target;
+}
+
+export async function writeCandidateToOpenClawMemory(
+  candidate: KnowledgeCandidate,
+): Promise<OpenClawFilePromotionResult> {
+  const workspaceDir = getOpenClawWorkspaceDir();
+  if (workspaceDir === null) {
+    return {
+      success: false,
+      error: "OpenClaw workspace is not configured. Set OPENCLAW_WORKSPACE_DIR.",
+    };
+  }
+
+  const relativePath = buildOpenClawMemoryRelativePath(candidate);
+  const target = resolveTargetPath(workspaceDir, relativePath);
+  if (target === null) {
+    return {
+      success: false,
+      error: "OpenClaw memory target resolved outside OPENCLAW_WORKSPACE_DIR.",
+    };
+  }
+
+  try {
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(target, buildOpenClawMemoryMarkdown(candidate), "utf8");
+  } catch (error) {
+    return {
+      success: false,
+      error: `OpenClaw memory file write failed: ${String(error)}`,
+    };
+  }
+
+  return {
+    success: true,
+    memoryId: `openclaw-file:${relativePath}`,
+    relativePath,
+    absolutePath: target,
+  };
+}

package/src/lib/providerTestPrompt.ts

@@ -0,0 +1,78 @@
+export type ProviderTestMode = "non-streaming" | "streaming";
+
+export type ProviderTestMessage = {
+  role: "user";
+  content: string;
+};
+
+export type ProviderTestRequestBody = {
+  model: string;
+  messages: ProviderTestMessage[];
+  max_tokens: number;
+  stream?: true;
+};
+
+const MEMORY_PROBE_FACTS = [
+  "Project fact: Agent Inspector captures LLM traffic and turns it into Raw Trace, Session Episode, and Memory Candidate layers.",
+  "Procedure: before release, run bun test, npm run typecheck, npm run lint, npm run build, and openspec validate --all --strict.",
+  "Preference: the user prefers Chinese summaries, explicit verification, and commit/push/release closure when requested.",
+  "Pitfall: preserve .llm-inspector config compatibility; do not write raw logs or secrets into durable memory.",
+  "OpenClaw boundary: Agent Inspector owns L1-L3; OpenClaw owns durable indexing, retrieval, and recall.",
+];
+
+function modeInstruction(mode: ProviderTestMode): string {
+  switch (mode) {
+    case "non-streaming":
+      return "Reply in four concise bullets.";
+    case "streaming":
+      return "Reply in three concise bullets.";
+  }
+}
+
+function maxTokensForMode(mode: ProviderTestMode): number {
+  switch (mode) {
+    case "non-streaming":
+      return 1024;
+    case "streaming":
+      return 384;
+  }
+}
+
+export function buildProviderTestUserPrompt(mode: ProviderTestMode): string {
+  return [
+    "You are validating an LLM provider connection for Agent Inspector.",
+    "This request includes a synthetic memory probe so Agent Inspector can verify its three Inspector-owned memory layers.",
+    "",
+    "Synthetic memory probe:",
+    ...MEMORY_PROBE_FACTS.map((fact) => `- ${fact}`),
+    "",
+    "Return:",
+    "1. connection status",
+    "2. one project fact",
+    "3. one reusable procedure",
+    "4. one caution",
+    "",
+    modeInstruction(mode),
+  ].join("\n");
+}
+
+export function buildProviderTestMessages(mode: ProviderTestMode): ProviderTestMessage[] {
+  return [{ role: "user", content: buildProviderTestUserPrompt(mode) }];
+}
+
+export function buildProviderTestRequestBody(
+  model: string,
+  mode: ProviderTestMode,
+): ProviderTestRequestBody {
+  const base = {
+    model,
+    messages: buildProviderTestMessages(mode),
+    max_tokens: maxTokensForMode(mode),
+  };
+  switch (mode) {
+    case "non-streaming":
+      return base;
+    case "streaming":
+      return { ...base, stream: true };
+  }
+}

package/src/routes/api/providers.$providerId.test.log.ts

@@ -2,6 +2,7 @@ import { createFileRoute } from "@tanstack/react-router";
 import { getProvider, getModelUsageName } from "../../proxy/providers";
 import { appendLogEntry } from "../../proxy/logger";
 import { addTestLogEntry } from "../../proxy/store";
+import { buildProviderTestRequestBody } from "../../lib/providerTestPrompt";
 import {
   ProviderTestResultsSchema,
   type ProviderTestResult as TestResult,
@@ -63,11 +64,7 @@ async function logModelResults(
       const nonStreamingResult = nsResult;
       const streamingResult = sResult;
 
-      const requestBody = JSON.stringify({
-        model: usageModel,
-        messages: [{ role: "user", content: "say hello and briefly introduce yourself" }],
-        max_tokens: 1024,
-      });
+      const requestBody = JSON.stringify(buildProviderTestRequestBody(usageModel, "non-streaming"));
       const upstreamUrl = `${anthropicUrl}/v1/messages`;
 
       await addTestLogEntry({
@@ -104,12 +101,9 @@ async function logModelResults(
         ),
       );
 
-      const streamingRequestBody = JSON.stringify({
-        model: usageModel,
-        messages: [{ role: "user", content: "say hello" }],
-        max_tokens: 256,
-        stream: true,
-      });
+      const streamingRequestBody = JSON.stringify(
+        buildProviderTestRequestBody(usageModel, "streaming"),
+      );
 
       await addTestLogEntry({
         timestamp: new Date().toISOString(),
@@ -155,11 +149,7 @@ async function logModelResults(
       const nonStreamingResult = nsResult;
       const streamingResult = sResult;
 
-      const requestBody = JSON.stringify({
-        model: usageModel,
-        messages: [{ role: "user", content: "say hello and briefly introduce yourself" }],
-        max_tokens: 1024,
-      });
+      const requestBody = JSON.stringify(buildProviderTestRequestBody(usageModel, "non-streaming"));
       const upstreamUrl = `${openaiUrl}/v1/chat/completions`;
 
       await addTestLogEntry({
@@ -196,12 +186,9 @@ async function logModelResults(
         ),
       );
 
-      const streamingRequestBody = JSON.stringify({
-        model: usageModel,
-        messages: [{ role: "user", content: "say hello" }],
-        max_tokens: 256,
-        stream: true,
-      });
+      const streamingRequestBody = JSON.stringify(
+        buildProviderTestRequestBody(usageModel, "streaming"),
+      );
 
       await addTestLogEntry({
         timestamp: new Date().toISOString(),

package/.output/public/assets/_sessionId-DsNRbnNm.js

@@ -1 +0,0 @@
-import{R as s,j as e}from"./main-DHs7FBK3.js";import{P as i}from"./ProxyViewerContainer-pEBqVp1d.js";function t(){const{sessionId:o}=s.useParams();return e.jsx(i,{initialSessionId:o},o)}export{t as component};