@martian-engineering/lossless-claw 0.1.4 → 0.1.5

package/index.ts

@@ -49,6 +49,13 @@ type PluginEnvSnapshot = {
 
 type ReadEnvFn = (key: string) => string | undefined;
 
+type CompleteSimpleOptions = {
+  apiKey?: string;
+  maxTokens: number;
+  temperature?: number;
+  reasoning?: string;
+};
+
 /** Capture plugin env values once during initialization. */
 function snapshotPluginEnv(env: NodeJS.ProcessEnv = process.env): PluginEnvSnapshot {
   return {
@@ -130,13 +137,17 @@ type PiAiModule = {
       contextWindow?: number;
       maxTokens?: number;
     },
-    request: { messages: Array<{ role: string; content: unknown; timestamp?: number }> },
+    request: {
+      systemPrompt?: string;
+      messages: Array<{ role: string; content: unknown; timestamp?: number }>;
+    },
     options: {
       apiKey?: string;
       maxTokens: number;
       temperature?: number;
+      reasoning?: string;
     },
-  ) => Promise<{ content?: Array<{ type: string; text?: string }> }>;
+  ) => Promise<Record<string, unknown> & { content?: Array<{ type: string; text?: string }> }>;
   getModel?: (provider: string, modelId: string) => unknown;
   getModels?: (provider: string) => unknown[];
   getEnvApiKey?: (provider: string) => string | undefined;
@@ -173,6 +184,39 @@ function inferApiFromProvider(provider: string): string {
   return map[normalized] ?? "openai-responses";
 }
 
+/** Codex Responses rejects `temperature`; omit it for that API family. */
+export function shouldOmitTemperatureForApi(api: string | undefined): boolean {
+  return (api ?? "").trim().toLowerCase() === "openai-codex-responses";
+}
+
+/** Build provider-aware options for pi-ai completeSimple. */
+export function buildCompleteSimpleOptions(params: {
+  api: string | undefined;
+  apiKey: string | undefined;
+  maxTokens: number;
+  temperature: number | undefined;
+  reasoning: string | undefined;
+}): CompleteSimpleOptions {
+  const options: CompleteSimpleOptions = {
+    apiKey: params.apiKey,
+    maxTokens: params.maxTokens,
+  };
+
+  if (
+    typeof params.temperature === "number" &&
+    Number.isFinite(params.temperature) &&
+    !shouldOmitTemperatureForApi(params.api)
+  ) {
+    options.temperature = params.temperature;
+  }
+
+  if (typeof params.reasoning === "string" && params.reasoning.trim()) {
+    options.reasoning = params.reasoning.trim();
+  }
+
+  return options;
+}
+
 /** Select provider-specific config values with case-insensitive provider keys. */
 function findProviderConfigValue<T>(
   map: Record<string, T> | undefined,
@@ -566,8 +610,10 @@ function createLcmDependencies(api: OpenClawPluginApi): LcmDependencies {
       agentDir,
       runtimeConfig,
       messages,
+      system,
       maxTokens,
       temperature,
+      reasoning,
     }) => {
       try {
         const piAiModuleId = "@mariozechner/pi-ai";
@@ -644,24 +690,62 @@ function createLcmDependencies(api: OpenClawPluginApi): LcmDependencies {
           });
         }
 
+        const completeOptions = buildCompleteSimpleOptions({
+          api: resolvedModel.api,
+          apiKey: resolvedApiKey,
+          maxTokens,
+          temperature,
+          reasoning,
+        });
+
         const result = await mod.completeSimple(
           resolvedModel,
           {
+            ...(typeof system === "string" && system.trim()
+              ? { systemPrompt: system.trim() }
+              : {}),
             messages: messages.map((message) => ({
               role: message.role,
               content: message.content,
               timestamp: Date.now(),
             })),
           },
-          {
-            apiKey: resolvedApiKey,
-            maxTokens,
-            temperature,
-          },
+          completeOptions,
         );
 
+        if (!isRecord(result)) {
+          return {
+            content: [],
+            request_provider: providerId,
+            request_model: modelId,
+            request_api: resolvedModel.api,
+            request_reasoning:
+              typeof reasoning === "string" && reasoning.trim() ? reasoning.trim() : "(none)",
+            request_has_system:
+              typeof system === "string" && system.trim().length > 0 ? "true" : "false",
+            request_temperature:
+              typeof completeOptions.temperature === "number"
+                ? String(completeOptions.temperature)
+                : "(omitted)",
+            request_temperature_sent:
+              typeof completeOptions.temperature === "number" ? "true" : "false",
+          };
+        }
+
         return {
-          content: Array.isArray(result?.content) ? result.content : [],
+          ...result,
+          content: Array.isArray(result.content) ? result.content : [],
+          request_provider: providerId,
+          request_model: modelId,
+          request_api: resolvedModel.api,
+          request_reasoning:
+            typeof reasoning === "string" && reasoning.trim() ? reasoning.trim() : "(none)",
+          request_has_system: typeof system === "string" && system.trim().length > 0 ? "true" : "false",
+          request_temperature:
+            typeof completeOptions.temperature === "number"
+              ? String(completeOptions.temperature)
+              : "(omitted)",
+          request_temperature_sent: typeof completeOptions.temperature === "number" ? "true" : "false",
         };
       } catch (err) {
         console.error(`[lcm] completeSimple error:`, err instanceof Error ? err.message : err);
@@ -715,8 +799,8 @@ function createLcmDependencies(api: OpenClawPluginApi): LcmDependencies {
       }
 
       const provider = (
-        providerHint?.trim() ||
         envSnapshot.lcmSummaryProvider ||
+        providerHint?.trim() ||
         envSnapshot.openclawProvider ||
         "openai"
       ).trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martian-engineering/lossless-claw",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Lossless Context Management plugin for OpenClaw — DAG-based conversation summarization with incremental compaction",
   "type": "module",
   "main": "index.ts",

package/src/summarize.ts

@@ -24,6 +24,14 @@ export type LcmSummarizerLegacyParams = {
 type SummaryMode = "normal" | "aggressive";
 
 const DEFAULT_CONDENSED_TARGET_TOKENS = 2000;
+const LCM_SUMMARIZER_SYSTEM_PROMPT =
+  "You are a context-compaction summarization engine. Follow user instructions exactly and return plain text summary content only.";
+const DIAGNOSTIC_MAX_DEPTH = 4;
+const DIAGNOSTIC_MAX_ARRAY_ITEMS = 8;
+const DIAGNOSTIC_MAX_OBJECT_KEYS = 16;
+const DIAGNOSTIC_MAX_CHARS = 1200;
+const DIAGNOSTIC_SENSITIVE_KEY_PATTERN =
+  /(api[-_]?key|authorization|token|secret|password|cookie|set-cookie|private[-_]?key|bearer)/i;
 
 /** Normalize provider ids for stable config/profile lookup. */
 function normalizeProviderId(provider: string): string {
@@ -193,6 +201,202 @@ function formatBlockTypes(blockTypes: string[]): string {
   return blockTypes.join(",");
 }
 
+/** Truncate long diagnostic text values to keep logs bounded and readable. */
+function truncateDiagnosticText(value: string, maxChars = DIAGNOSTIC_MAX_CHARS): string {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  return `${value.slice(0, maxChars)}...[truncated:${value.length - maxChars} chars]`;
+}
+
+/** Build a JSON-safe, redacted, depth-limited clone for diagnostic logging. */
+function sanitizeForDiagnostics(value: unknown, depth = 0): unknown {
+  if (depth >= DIAGNOSTIC_MAX_DEPTH) {
+    return "[max-depth]";
+  }
+  if (typeof value === "string") {
+    return truncateDiagnosticText(value);
+  }
+  if (
+    value === null ||
+    typeof value === "number" ||
+    typeof value === "boolean" ||
+    typeof value === "bigint"
+  ) {
+    return value;
+  }
+  if (value === undefined) {
+    return "[undefined]";
+  }
+  if (typeof value === "function") {
+    return "[function]";
+  }
+  if (typeof value === "symbol") {
+    return "[symbol]";
+  }
+  if (Array.isArray(value)) {
+    const head = value
+      .slice(0, DIAGNOSTIC_MAX_ARRAY_ITEMS)
+      .map((entry) => sanitizeForDiagnostics(entry, depth + 1));
+    if (value.length > DIAGNOSTIC_MAX_ARRAY_ITEMS) {
+      head.push(`[+${value.length - DIAGNOSTIC_MAX_ARRAY_ITEMS} more items]`);
+    }
+    return head;
+  }
+  if (!isRecord(value)) {
+    return String(value);
+  }
+
+  const out: Record<string, unknown> = {};
+  const entries = Object.entries(value);
+  for (const [key, entry] of entries.slice(0, DIAGNOSTIC_MAX_OBJECT_KEYS)) {
+    out[key] = DIAGNOSTIC_SENSITIVE_KEY_PATTERN.test(key)
+      ? "[redacted]"
+      : sanitizeForDiagnostics(entry, depth + 1);
+  }
+  if (entries.length > DIAGNOSTIC_MAX_OBJECT_KEYS) {
+    out.__truncated_keys__ = entries.length - DIAGNOSTIC_MAX_OBJECT_KEYS;
+  }
+  return out;
+}
+
+/** Encode diagnostic payloads in a compact JSON string with safety guards. */
+function formatDiagnosticPayload(value: unknown): string {
+  try {
+    const json = JSON.stringify(sanitizeForDiagnostics(value));
+    if (!json) {
+      return "\"\"";
+    }
+    return truncateDiagnosticText(json);
+  } catch {
+    return "\"[unserializable]\"";
+  }
+}
+
+/**
+ * Extract safe diagnostic metadata from a provider response envelope.
+ *
+ * Picks common metadata fields (request id, model echo, usage counters) without
+ * leaking secrets like API keys or auth tokens. The result object from
+ * `deps.complete` is typed narrowly but real provider responses carry extra
+ * fields that are useful for debugging empty-summary incidents.
+ */
+function extractResponseDiagnostics(result: unknown): string {
+  if (!isRecord(result)) {
+    return "";
+  }
+
+  const parts: string[] = [];
+
+  // Envelope-shape diagnostics for empty-block incidents.
+  const topLevelKeys = Object.keys(result).slice(0, 24);
+  if (topLevelKeys.length > 0) {
+    parts.push(`keys=${topLevelKeys.join(",")}`);
+  }
+  if ("content" in result) {
+    const contentVal = result.content;
+    if (Array.isArray(contentVal)) {
+      parts.push(`content_kind=array`);
+      parts.push(`content_len=${contentVal.length}`);
+    } else if (contentVal === null) {
+      parts.push(`content_kind=null`);
+    } else {
+      parts.push(`content_kind=${typeof contentVal}`);
+    }
+    parts.push(`content_preview=${formatDiagnosticPayload(contentVal)}`);
+  } else {
+    parts.push("content_kind=missing");
+  }
+
+  // Preview common non-content payload envelopes used by provider SDKs.
+  const envelopePayload: Record<string, unknown> = {};
+  for (const key of ["summary", "output", "message", "response"]) {
+    if (key in result) {
+      envelopePayload[key] = result[key];
+    }
+  }
+  if (Object.keys(envelopePayload).length > 0) {
+    parts.push(`payload_preview=${formatDiagnosticPayload(envelopePayload)}`);
+  }
+
+  // Request / response id — present in most provider envelopes.
+  for (const key of ["id", "request_id", "x-request-id"]) {
+    const val = result[key];
+    if (typeof val === "string" && val.trim()) {
+      parts.push(`${key}=${val.trim()}`);
+    }
+  }
+
+  // Model echo — useful when the provider selects a different checkpoint.
+  if (typeof result.model === "string" && result.model.trim()) {
+    parts.push(`resp_model=${result.model.trim()}`);
+  }
+  if (typeof result.provider === "string" && result.provider.trim()) {
+    parts.push(`resp_provider=${result.provider.trim()}`);
+  }
+  for (const key of [
+    "request_provider",
+    "request_model",
+    "request_api",
+    "request_reasoning",
+    "request_has_system",
+    "request_temperature",
+    "request_temperature_sent",
+  ]) {
+    const val = result[key];
+    if (typeof val === "string" && val.trim()) {
+      parts.push(`${key}=${val.trim()}`);
+    }
+  }
+
+  // Usage counters — safe numeric diagnostics.
+  if (isRecord(result.usage)) {
+    const u = result.usage;
+    const tokens: string[] = [];
+    for (const k of [
+      "prompt_tokens",
+      "completion_tokens",
+      "total_tokens",
+      "input",
+      "output",
+      "cacheRead",
+      "cacheWrite",
+    ]) {
+      if (typeof u[k] === "number") {
+        tokens.push(`${k}=${u[k]}`);
+      }
+    }
+    if (tokens.length > 0) {
+      parts.push(tokens.join(","));
+    }
+  }
+
+  // Finish reason — helps explain empty content.
+  const finishReason =
+    typeof result.finish_reason === "string"
+      ? result.finish_reason
+      : typeof result.stopReason === "string"
+        ? result.stopReason
+      : typeof result.stop_reason === "string"
+        ? result.stop_reason
+        : undefined;
+  if (finishReason) {
+    parts.push(`finish=${finishReason}`);
+  }
+
+  // Provider-level error payloads (most useful when finish=error and content is empty).
+  const errorMessage = result.errorMessage;
+  if (typeof errorMessage === "string" && errorMessage.trim()) {
+    parts.push(`error_message=${truncateDiagnosticText(errorMessage.trim(), 400)}`);
+  }
+  const errorPayload = result.error;
+  if (errorPayload !== undefined) {
+    parts.push(`error_preview=${formatDiagnosticPayload(errorPayload)}`);
+  }
+
+  return parts.join("; ");
+}
+
 /**
  * Resolve a practical target token count for leaf and condensed summaries.
  * Aggressive leaf mode intentionally aims lower so compaction converges faster.
@@ -522,6 +726,7 @@ export async function createLcmSummarizeFromLegacyParams(params: {
       authProfileId,
       agentDir,
       runtimeConfig: params.legacyParams.config,
+      system: LCM_SUMMARIZER_SYSTEM_PROMPT,
       messages: [
         {
           role: "user",
@@ -533,17 +738,111 @@ export async function createLcmSummarizeFromLegacyParams(params: {
     });
 
     const normalized = normalizeCompletionSummary(result.content);
-    const summary = normalized.summary;
+    let summary = normalized.summary;
+    let summarySource: "content" | "envelope" | "retry" | "fallback" = "content";
 
+    // --- Empty-summary hardening: envelope → retry → deterministic fallback ---
     if (!summary) {
+      // Envelope-aware extraction: some providers place summary text in
+      // top-level response fields (output, message, response) rather than
+      // inside the content array.  Re-run normalization against the full
+      // response envelope before spending an API call on a retry.
+      const envelopeNormalized = normalizeCompletionSummary(result);
+      if (envelopeNormalized.summary) {
+        summary = envelopeNormalized.summary;
+        summarySource = "envelope";
+        console.error(
+          `[lcm] recovered summary from response envelope; provider=${provider}; model=${model}; ` +
+            `block_types=${formatBlockTypes(envelopeNormalized.blockTypes)}; source=envelope`,
+        );
+      }
+    }
+
+    if (!summary) {
+      const responseDiag = extractResponseDiagnostics(result);
+      const diagParts = [
+        `[lcm] empty normalized summary on first attempt`,
+        `provider=${provider}`,
+        `model=${model}`,
+        `block_types=${formatBlockTypes(normalized.blockTypes)}`,
+        `response_blocks=${result.content.length}`,
+      ];
+      if (responseDiag) {
+        diagParts.push(responseDiag);
+      }
+      console.error(`${diagParts.join("; ")}; retrying with conservative settings`);
+
+      // Single retry with conservative parameters: low temperature and low
+      // reasoning budget to coax a textual response from providers that
+      // sometimes return reasoning-only or empty blocks on the first pass.
+      try {
+        const retryResult = await params.deps.complete({
+          provider,
+          model,
+          apiKey,
+          providerApi,
+          authProfileId,
+          agentDir,
+          runtimeConfig: params.legacyParams.config,
+          system: LCM_SUMMARIZER_SYSTEM_PROMPT,
+          messages: [
+            {
+              role: "user",
+              content: prompt,
+            },
+          ],
+          maxTokens: targetTokens,
+          temperature: 0.05,
+          reasoning: "low",
+        });
+
+        const retryNormalized = normalizeCompletionSummary(retryResult.content);
+        summary = retryNormalized.summary;
+
+        if (summary) {
+          summarySource = "retry";
+          console.error(
+            `[lcm] retry succeeded; provider=${provider}; model=${model}; ` +
+              `block_types=${formatBlockTypes(retryNormalized.blockTypes)}; source=retry`,
+          );
+        } else {
+          const retryDiag = extractResponseDiagnostics(retryResult);
+          const retryParts = [
+            `[lcm] retry also returned empty summary`,
+            `provider=${provider}`,
+            `model=${model}`,
+            `block_types=${formatBlockTypes(retryNormalized.blockTypes)}`,
+            `response_blocks=${retryResult.content.length}`,
+          ];
+          if (retryDiag) {
+            retryParts.push(retryDiag);
+          }
+          console.error(`${retryParts.join("; ")}; falling back to truncation`);
+        }
+      } catch (retryErr) {
+        // Retry is best-effort; log and proceed to deterministic fallback.
+        console.error(
+          `[lcm] retry failed; provider=${provider} model=${model}; error=${
+            retryErr instanceof Error ? retryErr.message : String(retryErr)
+          }; falling back to truncation`,
+        );
+      }
+    }
+
+    if (!summary) {
+      summarySource = "fallback";
       console.error(
-        `[lcm] summarize empty normalized summary; provider=${provider} model=${model} block_types=${formatBlockTypes(
-          normalized.blockTypes,
-        )}; response_blocks=${result.content.length}; falling back to truncation`,
+        `[lcm] all extraction attempts exhausted; provider=${provider}; model=${model}; source=fallback`,
       );
       return buildDeterministicFallbackSummary(text, targetTokens);
     }
 
+    if (summarySource !== "content") {
+      console.error(
+        `[lcm] summary resolved via non-content path; provider=${provider}; model=${model}; source=${summarySource}`,
+      );
+    }
+
     return summary;
   };
 }

package/src/types.ts

@@ -11,6 +11,17 @@ import type { LcmConfig } from "./db/config.js";
  * Minimal LLM completion interface needed by LCM for summarization.
  * Matches the signature of completeSimple from @mariozechner/pi-ai.
  */
+export type CompletionContentBlock = {
+  type: string;
+  text?: string;
+  [key: string]: unknown;
+};
+
+export type CompletionResult = {
+  content: CompletionContentBlock[];
+  [key: string]: unknown;
+};
+
 export type CompleteFn = (params: {
   provider?: string;
   model: string;
@@ -24,7 +35,7 @@ export type CompleteFn = (params: {
   maxTokens: number;
   temperature?: number;
   reasoning?: string;
-}) => Promise<{ content: Array<{ type: string; text?: string }> }>;
+}) => Promise<CompletionResult>;
 
 /**
  * Gateway RPC call interface.