@martian-engineering/lossless-claw 0.1.2 → 0.1.5

package/README.md

@@ -1,5 +1,7 @@
 # lossless-claw
 
+> ⚠️ **Current requirement:** This plugin currently requires a custom OpenClaw build with [PR #22201](https://github.com/openclaw/openclaw/pull/22201) applied until that PR is merged upstream.
+
 Lossless Context Management plugin for [OpenClaw](https://github.com/openclaw/openclaw), based on the [LCM paper](https://voltropy.com/LCM). Replaces OpenClaw's built-in sliding-window compaction with a DAG-based summarization system that preserves every message while keeping active context within model token limits.
 
 ## What it does
@@ -26,45 +28,37 @@ Nothing is lost. Raw messages stay in the database. Summaries link back to their
 
 ### Install the plugin
 
-**From npm** (recommended):
+Use OpenClaw's plugin installer (recommended):
 
 ```bash
-npm install @martian-engineering/lossless-claw
+openclaw plugins install @martian-engineering/lossless-claw
 ```
 
-**From source** (for development):
+If you're running from a local OpenClaw checkout, use:
 
 ```bash
-git clone https://github.com/Martian-Engineering/lossless-claw.git
-cd lossless-claw
-npm install
+pnpm openclaw plugins install @martian-engineering/lossless-claw
 ```
 
-### Configure OpenClaw
-
-Add the plugin to your OpenClaw config (`~/.openclaw/openclaw.json`):
+For local plugin development, link your working copy instead of copying files:
 
-```json
-{
-  "plugins": {
-    "paths": [
-      "node_modules/@martian-engineering/lossless-claw"
-    ],
-    "slots": {
-      "contextEngine": "lossless-claw"
-    }
-  }
-}
+```bash
+openclaw plugins install --link /path/to/lossless-claw
+# or from a local OpenClaw checkout:
+# pnpm openclaw plugins install --link /path/to/lossless-claw
 ```
 
-If installed from source, use the absolute path to the cloned repo instead:
+The install command records the plugin, enables it, and applies compatible slot selection (including `contextEngine` when applicable).
+
+### Configure OpenClaw
+
+In most cases, no manual JSON edits are needed after `openclaw plugins install`.
+
+If you need to set it manually, ensure the context engine slot points at lossless-claw:
 
 ```json
 {
   "plugins": {
-    "paths": [
-      "/path/to/lossless-claw"
-    ],
     "slots": {
       "contextEngine": "lossless-claw"
     }
@@ -72,8 +66,6 @@ If installed from source, use the absolute path to the cloned repo instead:
 }
 ```
 
-The `slots.contextEngine` setting tells OpenClaw to route all context management through LCM instead of the built-in legacy engine.
-
 Restart OpenClaw after configuration changes.
 
 ## Configuration

package/docs/architecture.md

@@ -67,8 +67,10 @@ The **leaf pass** converts raw messages into leaf summaries:
 3. Concatenate message content with timestamps.
 4. Resolve the most recent prior summary for continuity (passed as `previous_context` so the LLM avoids repeating known information).
 5. Send to the LLM with the leaf prompt.
-6. If the summary is larger than the input (LLM failure), retry with the aggressive prompt. If still too large, fall back to deterministic truncation.
-7. Persist the summary, link to source messages, and replace the message range in context_items.
+6. Normalize provider response blocks (Anthropic/OpenAI text, output_text, and nested content/summary shapes) into plain text.
+7. If normalization is empty, log provider/model/block-type diagnostics and fall back to deterministic truncation.
+8. If the summary is larger than the input (LLM failure), retry with the aggressive prompt. If still too large, fall back to deterministic truncation.
+9. Persist the summary, link to source messages, and replace the message range in context_items.
 
 ### Condensation
 
@@ -215,8 +217,8 @@ All mutating operations (ingest, compact) are serialized per-session using a pro
 
 LCM needs to call an LLM for summarization. It resolves credentials through a three-tier cascade:
 
-1. **Explicit API key** — If provided in legacy params
+1. **Auth profiles** — OpenClaw's OAuth/token/API-key profile system (`auth-profiles.json`), checked in priority order
 2. **Environment variables** — Standard provider env vars (`ANTHROPIC_API_KEY`, etc.)
-3. **Auth profiles** — OpenClaw's OAuth/token/API-key profile system (`auth-profiles.json`)
+3. **Custom provider key** — From models config (e.g., `models.json`)
 
 For OAuth providers (e.g., Anthropic via Claude Max), LCM handles token refresh and credential persistence automatically.

package/docs/configuration.md

@@ -2,24 +2,25 @@
 
 ## Quick start
 
-Install the plugin and add it to your OpenClaw config:
+Install the plugin with OpenClaw's plugin installer:
 
 ```bash
-npm install @martian-engineering/lossless-claw
+openclaw plugins install @martian-engineering/lossless-claw
 ```
 
-```json
-{
-  "plugins": {
-    "paths": ["node_modules/@martian-engineering/lossless-claw"],
-    "slots": {
-      "contextEngine": "lossless-claw"
-    }
-  }
-}
+If you're running from a local OpenClaw checkout:
+
+```bash
+pnpm openclaw plugins install @martian-engineering/lossless-claw
+```
+
+For local development of this plugin, link your working copy:
+
+```bash
+openclaw plugins install --link /path/to/lossless-claw
 ```
 
-If installed from source, use the absolute path to the repo instead of `node_modules/...`.
+`openclaw plugins install` handles plugin registration/enabling and slot selection automatically.
 
 Set recommended environment variables:
 

package/docs/tui.md

@@ -176,7 +176,7 @@ Lists files that exceeded the large file threshold (default 25k tokens) and were
 Re-summarizes a single summary node using the current depth-aware prompt templates. The process:
 
 1. **Preview** — shows the prompt that will be sent, including source material, target token count, previous context, and time range
-2. **API call** — sends to Anthropic's API (Claude Sonnet by default)
+2. **API call** — sends to the configured provider API (Anthropic by default)
 3. **Review** — shows old and new content side-by-side with token delta. Toggle unified diff view with `d`. Scroll with `j`/`k`.
 
 | Key (Preview) | Action |
@@ -280,6 +280,9 @@ lcm-tui rewrite 44 --depth 0 --apply
 # Rewrite everything bottom-up
 lcm-tui rewrite 44 --all --apply --diff
 
+# Rewrite with OpenAI Responses API
+lcm-tui rewrite 44 --summary sum_abc123 --provider openai --model gpt-5.3-codex --apply
+
 # Use custom prompt templates
 lcm-tui rewrite 44 --all --apply --prompt-dir ~/.config/lcm-tui/prompts
 ```
@@ -292,7 +295,8 @@ lcm-tui rewrite 44 --all --apply --prompt-dir ~/.config/lcm-tui/prompts
 | `--apply` | Write changes to database |
 | `--dry-run` | Show before/after without writing (default) |
 | `--diff` | Show unified diff |
-| `--model <model>` | Anthropic model (default: `claude-sonnet-4-20250514`) |
+| `--provider <id>` | API provider (inferred from `--model` when omitted) |
+| `--model <model>` | API model (default depends on provider) |
 | `--prompt-dir <path>` | Custom prompt template directory |
 | `--timestamps` | Inject timestamps into source text (default: true) |
 | `--tz <timezone>` | Timezone for timestamps (default: system local) |
@@ -348,6 +352,56 @@ Everything runs in a single transaction.
 | `--apply` | Execute transplant |
 | `--dry-run` | Show what would be transplanted (default) |
 
+### `lcm-tui backfill`
+
+Imports a pre-LCM JSONL session into `conversations/messages/context_items`, runs iterative depth-aware compaction with the configured provider + prompt templates, optionally forces a single-root fold, and can transplant the result to another conversation.
+
+```bash
+# Preview import + compaction plan (no writes)
+lcm-tui backfill my-agent session_abc123
+
+# Import + compact
+lcm-tui backfill my-agent session_abc123 --apply
+
+# Re-run compaction for an already-imported session
+lcm-tui backfill my-agent session_abc123 --apply --recompact
+
+# Force a single summary root when possible
+lcm-tui backfill my-agent session_abc123 --apply --recompact --single-root
+
+# Import + compact + transplant into an active conversation
+lcm-tui backfill my-agent session_abc123 --apply --transplant-to 653
+
+# Backfill using OpenAI
+lcm-tui backfill my-agent session_abc123 --apply --provider openai --model gpt-5.3-codex
+```
+
+All write paths are transactional:
+1. Import transaction (conversation/messages/message_parts/context)
+2. Per-pass compaction transactions (leaf/condensed replacements)
+3. Optional transplant transaction (reuse of transplant command internals)
+
+An idempotency guard prevents duplicate imports for the same `session_id`.
+
+| Flag | Description |
+|------|-------------|
+| `--apply` | Execute import/compaction/transplant |
+| `--dry-run` | Show what would run, without writes (default) |
+| `--recompact` | Re-run compaction for already-imported sessions (message import remains idempotent) |
+| `--single-root` | Force condensed folding until one summary remains when possible |
+| `--transplant-to <conv_id>` | Transplant backfilled summaries into target conversation |
+| `--title <text>` | Override imported conversation title |
+| `--leaf-chunk-tokens <n>` | Max source tokens per leaf chunk |
+| `--leaf-target-tokens <n>` | Target output tokens for leaf summaries |
+| `--condensed-target-tokens <n>` | Target output tokens for condensed summaries |
+| `--leaf-fanout <n>` | Min leaves required for d1 condensation |
+| `--condensed-fanout <n>` | Min summaries required for d2+ condensation |
+| `--hard-fanout <n>` | Min summaries for forced single-root passes |
+| `--fresh-tail <n>` | Preserve freshest N raw messages from leaf compaction |
+| `--provider <id>` | API provider (inferred from model when omitted) |
+| `--model <id>` | API model (default depends on provider) |
+| `--prompt-dir <path>` | Custom depth-prompt directory |
+
 ### `lcm-tui prompts`
 
 Manage and inspect depth-aware prompt templates. Templates control how the LLM summarizes at each depth level.
@@ -404,21 +458,31 @@ All templates end with an `"Expand for details about:"` footer listing topics av
 
 ## Authentication
 
-The TUI needs an Anthropic API key for rewrite and repair operations. It resolves credentials in this order:
+The TUI resolves API keys by provider for rewrite, repair, and backfill compaction operations.
+
+- Anthropic: `ANTHROPIC_API_KEY`
+- OpenAI: `OPENAI_API_KEY`
 
-1. `ANTHROPIC_API_KEY` environment variable
-2. OpenClaw config (`~/.openclaw/openclaw.json`) — reads the `anthropic:default` auth profile mode
+Resolution order:
+1. Provider API key environment variable
+2. OpenClaw config (`~/.openclaw/openclaw.json`) — checks matching provider auth profile mode
 3. OpenClaw env file
 4. `~/.zshrc` export
-5. Various credential file candidates under `~/.openclaw/`
+5. Credential file candidates under `~/.openclaw/`
+
+If the provider auth profile mode is `oauth` (not `api_key`), set the provider API key environment variable explicitly.
+
+Interactive rewrite (`w`/`W`) can be configured with:
+- `LCM_TUI_SUMMARY_PROVIDER`
+- `LCM_TUI_SUMMARY_MODEL`
 
-If the auth profile mode is `oauth` (not `api_key`), the TUI cannot use it — set `ANTHROPIC_API_KEY` explicitly for repair/rewrite commands.
+It also honors `LCM_SUMMARY_PROVIDER` / `LCM_SUMMARY_MODEL` as fallback.
 
 ## Database
 
-The TUI operates directly on the SQLite database at `~/.openclaw/lcm.db`. All write operations (rewrite, dissolve, repair, transplant) use transactions. Changes take effect on the next conversation turn — the running OpenClaw instance picks up database changes automatically.
+The TUI operates directly on the SQLite database at `~/.openclaw/lcm.db`. All write operations (rewrite, dissolve, repair, transplant, backfill) use transactions. Changes take effect on the next conversation turn — the running OpenClaw instance picks up database changes automatically.
 
-**Backup recommendation:** Before batch operations (repair `--all`, rewrite `--all`, transplant), copy the database:
+**Backup recommendation:** Before batch operations (repair `--all`, rewrite `--all`, transplant, backfill), copy the database:
 
 ```bash
 cp ~/.openclaw/lcm.db ~/.openclaw/lcm.db.bak-$(date +%Y%m%d)
@@ -428,7 +492,7 @@ cp ~/.openclaw/lcm.db ~/.openclaw/lcm.db.bak-$(date +%Y%m%d)
 
 **"No LCM summaries found"** — The session may not have an associated conversation in the LCM database. Check that the `conv_id` column shows a non-zero value in the session list. Sessions without LCM tracking won't have summaries.
 
-**Rewrite returns empty/bad content** — Check the API key is valid and the model is accessible. The TUI uses `claude-sonnet-4-20250514` by default; override with `--model` if needed.
+**Rewrite returns empty/bad content** — Check provider/model access and API key. If normalization still yields empty text, the TUI now returns diagnostics including `provider`, `model`, and response `block_types` to help pinpoint adapter mismatches.
 
 **Dissolve fails with "not condensed"** — Only condensed summaries (depth > 0) can be dissolved. Leaf summaries have no parent summaries to restore.
 

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.2",
+  "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 {
@@ -78,13 +86,315 @@ function estimateTokens(text: string): number {
   return Math.ceil(text.length / 4);
 }
 
-/** Narrows completion response blocks to plain text blocks. */
-function isTextBlock(block: unknown): block is { type: string; text: string } {
-  if (!block || typeof block !== "object" || Array.isArray(block)) {
-    return false;
+/** Narrow unknown values to plain object records. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Normalize text fragments from provider-specific block shapes.
+ *
+ * Deduplicates exact repeated fragments while preserving first-seen order so
+ * providers that mirror output in multiple fields don't duplicate summaries.
+ */
+function normalizeTextFragments(chunks: string[]): string {
+  const normalized: string[] = [];
+  const seen = new Set<string>();
+
+  for (const chunk of chunks) {
+    const trimmed = chunk.trim();
+    if (!trimmed || seen.has(trimmed)) {
+      continue;
+    }
+    seen.add(trimmed);
+    normalized.push(trimmed);
+  }
+  return normalized.join("\n").trim();
+}
+
+/** Collect all nested `type` labels for diagnostics on normalization failures. */
+function collectBlockTypes(value: unknown, out: Set<string>): void {
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      collectBlockTypes(entry, out);
+    }
+    return;
+  }
+  if (!isRecord(value)) {
+    return;
+  }
+
+  if (typeof value.type === "string" && value.type.trim()) {
+    out.add(value.type.trim());
+  }
+  for (const nested of Object.values(value)) {
+    collectBlockTypes(nested, out);
+  }
+}
+
+/** Collect text payloads from common provider response shapes. */
+function collectTextLikeFields(value: unknown, out: string[]): void {
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      collectTextLikeFields(entry, out);
+    }
+    return;
+  }
+  if (!isRecord(value)) {
+    return;
+  }
+
+  for (const key of ["text", "output_text", "thinking"]) {
+    appendTextValue(value[key], out);
+  }
+  for (const key of ["content", "summary", "output", "message", "response"]) {
+    if (key in value) {
+      collectTextLikeFields(value[key], out);
+    }
+  }
+}
+
+/** Append raw textual values and nested text wrappers (`value`, `text`). */
+function appendTextValue(value: unknown, out: string[]): void {
+  if (typeof value === "string") {
+    out.push(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      appendTextValue(entry, out);
+    }
+    return;
+  }
+  if (!isRecord(value)) {
+    return;
+  }
+
+  if (typeof value.value === "string") {
+    out.push(value.value);
+  }
+  if (typeof value.text === "string") {
+    out.push(value.text);
+  }
+}
+
+/** Normalize provider completion content into a plain-text summary payload. */
+function normalizeCompletionSummary(content: unknown): { summary: string; blockTypes: string[] } {
+  const chunks: string[] = [];
+  const blockTypeSet = new Set<string>();
+
+  collectTextLikeFields(content, chunks);
+  collectBlockTypes(content, blockTypeSet);
+
+  const blockTypes = [...blockTypeSet].sort((a, b) => a.localeCompare(b));
+  return {
+    summary: normalizeTextFragments(chunks),
+    blockTypes,
+  };
+}
+
+/** Format normalized block types for concise diagnostics. */
+function formatBlockTypes(blockTypes: string[]): string {
+  if (blockTypes.length === 0) {
+    return "(none)";
+  }
+  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()}`);
+    }
   }
-  const record = block as { type?: unknown; text?: unknown };
-  return record.type === "text" && typeof record.text === "string";
+
+  // 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("; ");
 }
 
 /**
@@ -416,6 +726,7 @@ export async function createLcmSummarizeFromLegacyParams(params: {
       authProfileId,
       agentDir,
       runtimeConfig: params.legacyParams.config,
+      system: LCM_SUMMARIZER_SYSTEM_PROMPT,
       messages: [
         {
           role: "user",
@@ -426,18 +737,112 @@ export async function createLcmSummarizeFromLegacyParams(params: {
       temperature: aggressive ? 0.1 : 0.2,
     });
 
-    const summary = result.content
-      .filter(isTextBlock)
-      .map((block) => block.text.trim())
-      .filter(Boolean)
-      .join("\n")
-      .trim();
+    const normalized = normalizeCompletionSummary(result.content);
+    let summary = normalized.summary;
+    let summarySource: "content" | "envelope" | "retry" | "fallback" = "content";
 
+    // --- Empty-summary hardening: envelope → retry → deterministic fallback ---
     if (!summary) {
-      console.error(`[lcm] summarize got empty content from LLM (${result.content.length} blocks, types: ${result.content.map(b => b.type).join(",")}), falling back to truncation`);
+      // 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] 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.