@tonyclaw/agent-inspector 2.0.1 → 2.0.3

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/proxy/chunkStorage.ts

@@ -30,11 +30,10 @@ const StreamingChunksDataSchema = z.object({
   truncated: z.boolean().optional(),
 });
 
-const CHUNKS_DIR_ENV = process.env["CHUNKS_DIR"];
-
 export function getChunksDir(): string {
-  if (CHUNKS_DIR_ENV !== undefined) {
-    return isAbsolute(CHUNKS_DIR_ENV) ? CHUNKS_DIR_ENV : join(getDataDir(), CHUNKS_DIR_ENV);
+  const chunksDirEnv = process.env["CHUNKS_DIR"];
+  if (chunksDirEnv !== undefined && chunksDirEnv !== "") {
+    return isAbsolute(chunksDirEnv) ? chunksDirEnv : join(getDataDir(), chunksDirEnv);
   }
   return join(getDataDir(), "chunks");
 }

package/src/proxy/logger.ts

@@ -3,23 +3,14 @@ import { writeFileSync, mkdirSync } from "node:fs";
 import path from "node:path";
 import { getDataDir } from "./dataDir";
 
-const LOG_DIR_ENV = process.env["LOG_DIR"];
 const RETENTION_DAYS = Number(process.env["LOG_RETENTION_DAYS"] ?? "7");
-const LOG_FILE_ENV = process.env["AGENT_INSPECTOR_LOG_FILE"];
-
-let resolvedLogDir: string | null = null;
 
 export function resolveLogDir(): string {
-  if (resolvedLogDir !== null) return resolvedLogDir;
-
-  if (LOG_DIR_ENV !== undefined) {
-    resolvedLogDir = path.isAbsolute(LOG_DIR_ENV)
-      ? LOG_DIR_ENV
-      : path.join(getDataDir(), LOG_DIR_ENV);
-  } else {
-    resolvedLogDir = path.join(getDataDir(), "logs");
+  const logDirEnv = process.env["LOG_DIR"];
+  if (logDirEnv !== undefined && logDirEnv !== "") {
+    return path.isAbsolute(logDirEnv) ? logDirEnv : path.join(getDataDir(), logDirEnv);
   }
-  return resolvedLogDir;
+  return path.join(getDataDir(), "logs");
 }
 
 export function getLogFilePath(): string {
@@ -31,8 +22,9 @@ export function getLogFilePath(): string {
 }
 
 function getInspectorLogPath(): string {
-  if (LOG_FILE_ENV !== undefined) {
-    return LOG_FILE_ENV;
+  const logFileEnv = process.env["AGENT_INSPECTOR_LOG_FILE"];
+  if (logFileEnv !== undefined && logFileEnv !== "") {
+    return logFileEnv;
   }
   return path.join(getDataDir(), "logs", "inspector.log");
 }
@@ -43,6 +35,7 @@ export async function initLogger(): Promise<void> {
   const cutoff = Date.now() - retentionMs;
 
   try {
+    await mkdir(dir, { recursive: true });
     const entries = await readdir(dir);
     for (const entry of entries) {
       if (!entry.endsWith(".jsonl")) continue;

package/src/proxy/store.ts

@@ -5,14 +5,7 @@ import { createInterface } from "node:readline";
 import { Buffer } from "node:buffer";
 import { join } from "node:path";
 import { appendLogEntry, resolveLogDir, logger } from "./logger";
-import {
-  addToIndex,
-  findInIndex,
-  getNextLogId,
-  getCurrentLogFile,
-  saveIndex,
-  loadIndex,
-} from "./logIndex";
+import { addToIndex, findInIndex, getNextLogId, getCurrentLogFile } from "./logIndex";
 import { writeChunks } from "./chunkStorage";
 import type { CapturedLog } from "./schemas";
 import { CapturedLogSchema } from "./schemas";
@@ -67,17 +60,11 @@ function removeFromCache(id: number): void {
 }
 
 /**
- * Add a test log entry directly to the in-memory store (for dashboard display).
- * This is used by the provider test endpoint alongside appendLogEntry (file logging).
+ * Add a test log entry to the in-memory store and persistent log file.
+ * This is used by the provider test endpoint to seed the provider-test session.
  */
 export async function addTestLogEntry(entry: Omit<CapturedLog, "id">): Promise<CapturedLog> {
   const id = await getNextLogId();
-  // Update the index with the new maxId so subsequent calls get unique IDs
-  const index = await loadIndex();
-  if (id > index.maxId) {
-    index.maxId = id;
-    await saveIndex(index);
-  }
 
   // Persist streaming chunks to disk if present
   let streamingChunksPath: string | null = null;
@@ -100,6 +87,11 @@ export async function addTestLogEntry(entry: Omit<CapturedLog, "id">): Promise<C
     sessionId: session.id,
     streamingChunksPath,
   };
+
+  const logFile = getCurrentLogFile();
+  appendLogEntry(log);
+  await addToIndex(id, logFile, -1, -1);
+
   addToCache(log);
   observeSessionLog(log, session.source);
   emitLogUpdate(log);