@remnic/core 9.65.7 → 9.66.0

package/src/context-summary.ts

@@ -0,0 +1,182 @@
+/**
+ * Pure context summary seam (issue #2347).
+ *
+ * The only shared summary path: `LcmSummarizer` and active-context
+ * transforms both call `summarizeContextPure`. No DAG writes, no model
+ * client construction — callers inject the model seam (`SummarizeFn`).
+ */
+import { looksLikeMechanicalTelemetryTranscript } from "./telemetry-transcript.js";
+import { estimateTokenCount } from "./token-estimate.js";
+
+/** Model seam injected by the caller (orchestrator LLM path or a test stub). */
+export type SummarizeFn = (
+  text: string,
+  targetTokens: number,
+  aggressive: boolean,
+) => Promise<string | null>;
+
+export type ContextSummaryMethod = "deterministic" | "llm" | "auto";
+
+export interface PureContextSummaryResult {
+  text: string;
+  method: "llm" | "deterministic";
+  /** True when the requested path degraded (auto mode only). */
+  fallback: boolean;
+  modelUsed?: string;
+  /**
+   * Escalation level preserved for LCM callers: 0 normal LLM, 1 aggressive
+   * LLM, 2 deterministic truncation. Undefined when never escalated.
+   */
+  escalation?: number;
+}
+
+export interface SummarizeContextPureOptions {
+  /** LLM seam. Required for `llm`; without it `auto` degrades to deterministic. */
+  llm?: SummarizeFn;
+  /** Hard ceiling for deterministic truncation output. */
+  deterministicMaxTokens?: number;
+  /** Route obvious mechanical telemetry straight to truncation. */
+  telemetryPrefilterEnabled?: boolean;
+  /** Recorded verbatim in the result for telemetry. */
+  modelUsed?: string;
+}
+
+/** Thrown when `llm` mode cannot produce usable text (no silent fallback). */
+export class ContextSummaryUnavailableError extends Error {
+  constructor(reason: string) {
+    super(`context summary unavailable: ${reason}`);
+    this.name = "ContextSummaryUnavailableError";
+  }
+}
+
+const DEFAULT_DETERMINISTIC_MAX_TOKENS = 256;
+/** LLM output tolerance before an attempt is rejected as too long (LCM parity). */
+const OUTPUT_TOKEN_TOLERANCE = 1.5;
+const MIN_DETERMINISTIC_TOKENS = 1;
+
+/**
+ * Summarize text through the shared seam.
+ *
+ * - `deterministic`: safe truncation only, never throws, never calls the LLM.
+ * - `llm`: exactly one non-aggressive LLM call; failure or unusable output
+ *   throws {@link ContextSummaryUnavailableError} (fallback is not allowed).
+ * - `auto`: escalation ladder (LLM → aggressive LLM → deterministic), with
+ *   `fallback: true` and an `escalation` level on degradation.
+ */
+export async function summarizeContextPure(
+  text: string,
+  targetTokens: number,
+  method: ContextSummaryMethod,
+  options: SummarizeContextPureOptions = {},
+): Promise<PureContextSummaryResult> {
+  const deterministicMaxTokens = Math.max(
+    MIN_DETERMINISTIC_TOKENS,
+    options.deterministicMaxTokens ?? DEFAULT_DETERMINISTIC_MAX_TOKENS,
+  );
+
+  if (method === "deterministic") {
+    return {
+      text: deterministicTruncate(text, Math.min(targetTokens, deterministicMaxTokens)),
+      method: "deterministic",
+      fallback: false,
+    };
+  }
+
+  const usableLlm = options.llm ?? null;
+  if (method === "llm") {
+    if (!usableLlm) {
+      throw new ContextSummaryUnavailableError("no llm seam configured");
+    }
+    const result = await attemptLlm(usableLlm, text, targetTokens, false);
+    if (result === null) {
+      throw new ContextSummaryUnavailableError("llm path failed");
+    }
+    return { text: result, method: "llm", fallback: false, modelUsed: options.modelUsed };
+  }
+
+  // auto
+  if (options.telemetryPrefilterEnabled && looksLikeMechanicalTelemetryTranscript(text)) {
+    return {
+      text: deterministicTruncate(text, Math.min(targetTokens, deterministicMaxTokens)),
+      method: "deterministic",
+      fallback: true,
+      escalation: 2,
+    };
+  }
+
+  if (usableLlm) {
+    const normal = await attemptLlm(usableLlm, text, targetTokens, false);
+    if (normal !== null) {
+      return { text: normal, method: "llm", fallback: false, escalation: 0, modelUsed: options.modelUsed };
+    }
+    const aggressiveTarget = Math.max(32, Math.ceil(targetTokens * 0.5));
+    const aggressive = await attemptLlm(usableLlm, text, aggressiveTarget, true);
+    if (aggressive !== null) {
+      return { text: aggressive, method: "llm", fallback: true, escalation: 1, modelUsed: options.modelUsed };
+    }
+  }
+
+  return {
+    text: deterministicTruncate(text, deterministicMaxTokens),
+    method: "deterministic",
+    fallback: true,
+    escalation: 2,
+  };
+}
+
+/** One LLM attempt; null on error, empty, or over-tolerance output. */
+async function attemptLlm(
+  llm: SummarizeFn,
+  text: string,
+  targetTokens: number,
+  aggressive: boolean,
+): Promise<string | null> {
+  try {
+    const result = await llm(text, targetTokens, aggressive);
+    if (!result || result.trim().length === 0) return null;
+    if (estimateTokenCount(result) > targetTokens * OUTPUT_TOKEN_TOLERANCE) return null;
+    return result;
+  } catch {
+    return null;
+  }
+}
+
+/** Deterministic truncation: first and last sentence, plus middle truncation. */
+export function deterministicTruncate(text: string, maxTokens: number): string {
+  if (maxTokens <= 0 || estimateTokenCount(text) <= maxTokens) return text;
+
+  const sentences = text.split(/(?<=[.!?])\s+/).filter((s) => s.length > 0);
+  if (sentences.length <= 2) return clampToTokenBudget(text, maxTokens);
+
+  const first = sentences[0];
+  const last = sentences[sentences.length - 1];
+  const render = (middle: string[], truncated: boolean): string =>
+    `${first} ${middle.join(" ")}${truncated ? " [...] " : " "}${last}`;
+
+  const base = render([], false);
+  if (estimateTokenCount(base) > maxTokens) return clampToTokenBudget(text, maxTokens);
+  if (estimateTokenCount(render([], true)) > maxTokens) return base;
+
+  const middle: string[] = [];
+  for (let i = 1; i < sentences.length - 1; i++) {
+    const candidate = [...middle, sentences[i]];
+    const truncated = i < sentences.length - 2;
+    if (estimateTokenCount(render(candidate, truncated)) > maxTokens) break;
+    middle.push(sentences[i]);
+  }
+
+  const truncated = middle.length < sentences.length - 2;
+  return clampToTokenBudget(render(middle, truncated), maxTokens);
+}
+
+function clampToTokenBudget(text: string, maxTokens: number): string {
+  const codePoints = [...text];
+  let low = 0;
+  let high = codePoints.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (estimateTokenCount(codePoints.slice(0, mid).join("")) <= maxTokens) low = mid;
+    else high = mid - 1;
+  }
+  return codePoints.slice(0, low).join("");
+}

package/src/extraction-prompt-safety.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import type { FallbackLlmOptions } from "./fallback-llm.js";
 
 import { parseConfig } from "./config.js";
 import { ExtractionEngine } from "./extraction.js";
@@ -111,7 +112,11 @@ type LocalLlmFixture = {
 };
 
 type GatewayFixture = {
-  parseWithSchemaDetailed(messages: ChatMessage[]): Promise<unknown>;
+  parseWithSchemaDetailed(
+    messages: ChatMessage[],
+    schema: unknown,
+    options?: FallbackLlmOptions,
+  ): Promise<unknown>;
 };
 
 type DirectClientFixture = {
@@ -283,11 +288,13 @@ test("gateway extraction prompt uses placeholders and accepts an empty question
   const engine = new ExtractionEngine(parseConfig({ modelSource: "gateway" }));
   let calls = 0;
   let prompt = "";
+  let nativeSchema: Record<string, unknown> | undefined;
 
   const fallbackLlm: GatewayFixture = {
-    async parseWithSchemaDetailed(messages: ChatMessage[]) {
+    async parseWithSchemaDetailed(messages: ChatMessage[], _schema, options) {
       calls += 1;
       prompt = messages[0]?.content ?? "";
+      nativeSchema = options?.jsonSchema?.schema;
       return { modelUsed: "fixture-gateway", result: SOURCE_GROUNDED_EXTRACTION };
     },
   };
@@ -298,6 +305,11 @@ test("gateway extraction prompt uses placeholders and accepts an empty question
   assert.equal(calls, 1);
   assertSourceGroundedResult(result);
   assertSafeExtractionPrompt(prompt);
+  assert.match(prompt, /Return only valid JSON matching this shape/);
+  assert.equal(nativeSchema?.type, "object");
+  const properties = nativeSchema?.properties as Record<string, Record<string, unknown>>;
+  assert.equal(properties.facts?.type, "array");
+  assert.equal((properties.facts?.items as Record<string, unknown>)?.type, "object");
 });
 
 test("direct extraction prompt uses placeholders and accepts an empty question list", async () => {

package/src/extraction.ts

@@ -7,6 +7,7 @@ import { shouldRunProactivePass } from "./proactive-contention.js";
 import { FallbackLlmClient, fallbackLlmRuntimeContextFromConfig, gatewayTaskChainOptions } from "./fallback-llm.js";
 import { revalidateDependentsViaLlm, type RevalidationFastChatCompletion } from "./orchestration/dependency-revalidation.js";
 import {
+  ExtractionProviderOutputSchema,
   ExtractionResultSchema,
   ConsolidationResultSchema,
   IdentityConsolidationResultSchema,
@@ -60,6 +61,7 @@ import {
   buildProfileConsolidationSystemPrompt,
   eventTimePromptInstruction,
 } from "./extraction-prompt.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
 import {
   containsExtractionPlaceholder,
   extractionAttributes,
@@ -77,6 +79,14 @@ type ExtractedRelationshipResult = NonNullable<ExtractionResult["relationships"]
 
 const PROACTIVE_MIN_CONFIDENCE = 0.8;
 
+const EXTRACTION_PROVIDER_JSON_SCHEMA = zodToJsonSchema(
+  ExtractionProviderOutputSchema,
+  {
+    $refStrategy: "none",
+    effectStrategy: "input",
+  },
+) as Record<string, unknown>;
+
 function extractionEntityType(value: unknown): ExtractedEntityResult["type"] | undefined {
   const type = extractionText(value);
   if (
@@ -1289,7 +1299,12 @@ export class ExtractionEngine {
     this.profiler.startSpan("gateway-fallback", extractionTraceId);
     try {
       const messages = [
-        { role: "system" as const, content: buildExtractionInstructions(this.config, existingEntities, ambientCapture) },
+        {
+          role: "system" as const,
+          content:
+            buildExtractionInstructions(this.config, existingEntities, ambientCapture) +
+            `\n\nReturn only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:\n${EXTRACTION_RESPONSE_SHAPE}`,
+        },
         { role: "user" as const, content: conversation },
       ];
 
@@ -1302,6 +1317,11 @@ export class ExtractionEngine {
           temperature: 0.3,
           maxTokens: this.config.extractionMaxOutputTokens,
           timeoutMs: this.config.localLlmTimeoutMs,
+          jsonSchema: {
+            name: "extraction_result",
+            schema: EXTRACTION_PROVIDER_JSON_SCHEMA,
+            strict: false,
+          },
           signal,
         }),
       );

package/src/fallback-llm.test.ts

@@ -12,6 +12,70 @@ import {
   clearSecretCache,
 } from "./resolve-provider-secret.js";
 
+test("fallback llm sends native JSON schema to chat completions", { concurrency: false }, async () => {
+  clearModelsJsonCache();
+  clearSecretCache();
+  const llm = new FallbackLlmClient({
+    agents: { defaults: { model: { primary: "openai/test-model" } } },
+    models: { providers: { openai: { baseUrl: "https://openai.example/v1", api: "openai-completions", apiKey: "key", models: [] } } },
+  });
+  const originalFetch = globalThis.fetch;
+  let captured: Record<string, unknown> = {};
+  globalThis.fetch = (async (_url, init) => {
+    captured = JSON.parse(String(init?.body ?? "{}")) as Record<string, unknown>;
+    return new Response(JSON.stringify({ choices: [{ message: { content: '{"ok":true}' } }] }), { status: 200 });
+  }) as typeof fetch;
+  try {
+    await llm.chatCompletion([{ role: "user", content: "test" }], {
+      jsonSchema: { name: "test_result", schema: { type: "object", properties: { ok: { type: "boolean" } } }, strict: false },
+    });
+    assert.deepEqual(captured.response_format, {
+      type: "json_schema",
+      json_schema: {
+        name: "test_result",
+        strict: false,
+        schema: { type: "object", properties: { ok: { type: "boolean" } } },
+      },
+    });
+  } finally {
+    globalThis.fetch = originalFetch;
+    clearModelsJsonCache();
+    clearSecretCache();
+  }
+});
+
+test("fallback llm retries without native schema when the provider rejects it", { concurrency: false }, async () => {
+  clearModelsJsonCache();
+  clearSecretCache();
+  const llm = new FallbackLlmClient({
+    agents: { defaults: { model: { primary: "openai/test-model" } } },
+    models: { providers: { openai: { baseUrl: "https://openai.example/v1", api: "openai-completions", apiKey: "key", models: [] } } },
+  });
+  const originalFetch = globalThis.fetch;
+  const bodies: Array<Record<string, unknown>> = [];
+  globalThis.fetch = (async (_url, init) => {
+    const body = JSON.parse(String(init?.body ?? "{}")) as Record<string, unknown>;
+    bodies.push(body);
+    if (body.response_format) {
+      return new Response('response_format json_schema is unsupported', { status: 400 });
+    }
+    return new Response(JSON.stringify({ choices: [{ message: { content: '{"ok":true}' } }] }), { status: 200 });
+  }) as typeof fetch;
+  try {
+    const response = await llm.chatCompletion([{ role: "user", content: "test" }], {
+      jsonSchema: { name: "test_result", schema: { type: "object" } },
+    });
+    assert.equal(response?.content, '{"ok":true}');
+    assert.equal(bodies.length, 2);
+    assert.ok(bodies[0]?.response_format);
+    assert.equal(bodies[1]?.response_format, undefined);
+  } finally {
+    globalThis.fetch = originalFetch;
+    clearModelsJsonCache();
+    clearSecretCache();
+  }
+});
+
 test("fallback llm prefers the active gateway provider config over models.json", { concurrency: false }, async () => {
   __setModelsJsonForTest({
     "custom-provider": {
@@ -1711,3 +1775,73 @@ test("fallback llm redacts provider error bodies for sensitive calls", { concurr
 function disableGatewaySecretResolverForTest(): void {
   __setGatewayResolverForTest(async () => null);
 }
+
+test("fallback llm does not retry schema-stripping for unrelated unsupported errors", { concurrency: false }, async () => {
+  clearModelsJsonCache();
+  clearSecretCache();
+  const llm = new FallbackLlmClient({
+    agents: { defaults: { model: { primary: "openai/test-model" } } },
+    models: { providers: { openai: { baseUrl: "https://openai.example/v1", api: "openai-completions", apiKey: "key", models: [] } } },
+  });
+  const originalFetch = globalThis.fetch;
+  const bodies: Array<Record<string, unknown>> = [];
+  globalThis.fetch = (async (_url, init) => {
+    const body = JSON.parse(String(init?.body ?? "{}")) as Record<string, unknown>;
+    bodies.push(body);
+    // Unrelated provider error: "unsupported" without schema/format context.
+    return new Response(JSON.stringify({ error: { message: "'temperature' is unsupported with this model" } }), { status: 400 });
+  }) as typeof fetch;
+  try {
+    const response = await llm.chatCompletion([{ role: "user", content: "test" }], {
+      jsonSchema: { name: "test_result", schema: { type: "object" } },
+    });
+    assert.equal(response, null);
+    // Exactly one request: no schema-stripping duplicate for unrelated errors.
+    assert.equal(bodies.length, 1);
+  } finally {
+    globalThis.fetch = originalFetch;
+    clearModelsJsonCache();
+    clearSecretCache();
+  }
+});
+
+test("fallback llm retries without responsesJsonSchema when the Responses API rejects it and degrades the rest of the chain", { concurrency: false }, async () => {
+  clearModelsJsonCache();
+  clearSecretCache();
+  const llm = new FallbackLlmClient({
+    agents: { defaults: { model: { primary: "openai/test-model", fallbacks: ["openai/test-model-2"] } } },
+    models: { providers: { openai: { baseUrl: "https://openai.example/v1", api: "openai-responses", apiKey: "key", models: [] } } },
+  });
+  const originalFetch = globalThis.fetch;
+  const bodies: Array<Record<string, unknown>> = [];
+  globalThis.fetch = (async (_url, init) => {
+    const body = JSON.parse(String(init?.body ?? "{}")) as Record<string, unknown>;
+    bodies.push(body);
+    if ((body as { text?: { format?: unknown } }).text?.format) {
+      return new Response('text.format json_schema is unsupported', { status: 400 });
+    }
+    // Model 1 always fails content-wise; model 2 succeeds.
+    const model = String(body.model ?? "");
+    if (model.endsWith("test-model")) {
+      return new Response(JSON.stringify({ output_text: "not json" }), { status: 200 });
+    }
+    return new Response(JSON.stringify({ output_text: '{"ok":true}' }), { status: 200 });
+  }) as typeof fetch;
+  try {
+    const response = await llm.chatCompletion([{ role: "user", content: "test" }], {
+      responsesJsonSchema: { name: "test_result", schema: { type: "object" } },
+      acceptResponse: (r) => r.content.includes("ok"),
+    });
+    assert.ok(response?.content.includes("ok"));
+    // model1: schema attempt (rejected) + unstructured retry (bad output)
+    // model2: unstructured only — the schema must NOT be re-sent chain-wide.
+    assert.equal(bodies.length, 3);
+    assert.ok((bodies[0] as { text?: { format?: unknown } }).text?.format);
+    assert.equal((bodies[1] as { text?: { format?: unknown } }).text?.format, undefined);
+    assert.equal((bodies[2] as { text?: { format?: unknown } }).text?.format, undefined);
+  } finally {
+    globalThis.fetch = originalFetch;
+    clearModelsJsonCache();
+    clearSecretCache();
+  }
+});

package/src/fallback-llm.ts

@@ -27,6 +27,8 @@ export interface FallbackLlmOptions {
   store?: boolean;
   /** Request strict JSON output when a route uses the Responses API. */
   responsesJsonSchema?: { name: string; schema: Record<string, unknown> };
+  /** Request provider-native structured output on supported JSON transports. */
+  jsonSchema?: { name: string; schema: Record<string, unknown>; strict?: boolean };
   /** Hide provider error details that could echo private request content. */
   redactProviderErrors?: boolean;
   /** Explicit "provider/model" override to try before the configured chain. */
@@ -108,6 +110,22 @@ interface ModelRef {
   modelString: string;
 }
 
+function isUnsupportedJsonSchemaError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  // Require an HTTP status plus explicit schema/format context. A bare
+  // "unsupported" (e.g. "'temperature' is unsupported with this model") must
+  // NOT trigger the schema-stripping retry, or we pay a duplicate request
+  // for unrelated provider errors.
+  if (!/\b(?:400|404|422)\b/.test(message)) {
+    return false;
+  }
+  if (/(?:response[_ ]?format|json[_ ]?schema|structured[_ ]?output)/i.test(message)) {
+    return true;
+  }
+  // "unsupported" only counts when adjacent to schema/format terminology.
+  return /\bunsupported\b[\s\S]{0,40}\b(?:schema|format)\b/i.test(message);
+}
+
 const PROVIDER_ALIASES: Record<string, readonly string[]> = {
   "openai-codex": ["codex"],
   codex: ["openai-codex"],
@@ -199,8 +217,9 @@ export class FallbackLlmClient {
     }
 
     const runChain = async (
-      runOptions: FallbackLlmOptions,
+      initialOptions: FallbackLlmOptions,
     ): Promise<FallbackLlmResponse | null> => {
+      let runOptions = initialOptions;
       let lastRejectedResponse: FallbackLlmResponse | null = null;
       // Try each model in the chain
       for (let i = 0; i < models.length; i++) {
@@ -232,6 +251,47 @@ export class FallbackLlmClient {
           if (runOptions.signal?.aborted) {
             throw abortReason(runOptions.signal);
           }
+          if (
+            (runOptions.jsonSchema || runOptions.responsesJsonSchema) &&
+            isUnsupportedJsonSchemaError(err)
+          ) {
+            log.debug(`fallback LLM: ${model.modelString} rejected native JSON schema; retrying without it`);
+            // Degrade to prompt-only for the REST of the chain too, so an
+            // N-model chain where every provider rejects structured output
+            // costs N+1 requests instead of 2N.
+            runOptions = {
+              ...runOptions,
+              jsonSchema: undefined,
+              responsesJsonSchema: undefined,
+            };
+            try {
+              const result = await this.tryModel(model, messages, runOptions);
+              if (result) {
+                const response = {
+                  content: result.content,
+                  modelUsed: model.modelString,
+                  usage: result.usage,
+                };
+                if (!runOptions.acceptResponse || runOptions.acceptResponse(response)) {
+                  return response;
+                }
+                lastRejectedResponse = response;
+                log.debug(`fallback LLM: ${model.modelString} unstructured retry output rejected by acceptResponse, trying next model...`);
+                continue;
+              }
+            } catch (retryError) {
+              if (runOptions.signal?.aborted) throw abortReason(runOptions.signal);
+              const retryErrorMsg = runOptions.redactProviderErrors
+                ? "provider error details redacted"
+                : retryError instanceof Error
+                  ? retryError.message
+                  : String(retryError);
+              log.debug(
+                `fallback LLM: ${model.modelString} unstructured retry failed (${retryErrorMsg})`,
+              );
+            }
+            continue;
+          }
           const errorMsg = runOptions.redactProviderErrors
             ? "provider error details redacted"
             : err instanceof Error
@@ -736,6 +796,18 @@ export class FallbackLlmClient {
       ...buildChatCompletionTokenLimit(modelId, options.maxTokens ?? 4096, {
         assumeOpenAI,
       }),
+      ...(options.jsonSchema
+        ? {
+            response_format: {
+              type: "json_schema",
+              json_schema: {
+                name: options.jsonSchema.name,
+                strict: options.jsonSchema.strict ?? false,
+                schema: options.jsonSchema.schema,
+              },
+            },
+          }
+        : {}),
     };
 
     const response = await fetch(url, {
@@ -891,14 +963,14 @@ export class FallbackLlmClient {
         assumeOpenAI: shouldAssumeOpenAiChatCompletions(config.baseUrl),
       }),
       ...(options.store === undefined ? {} : { store: options.store }),
-      ...(options.responsesJsonSchema
+      ...(options.jsonSchema || options.responsesJsonSchema
         ? {
             text: {
               format: {
                 type: "json_schema",
-                name: options.responsesJsonSchema.name,
-                strict: true,
-                schema: options.responsesJsonSchema.schema,
+                name: (options.jsonSchema ?? options.responsesJsonSchema)!.name,
+                strict: (options.jsonSchema?.strict ?? (options.responsesJsonSchema ? true : false)),
+                schema: (options.jsonSchema ?? options.responsesJsonSchema)!.schema,
               },
             },
           }

package/src/index.ts

@@ -1,17 +1,10 @@
 /**
- * @remnic/core
- *
- * Framework-agnostic Remnic memory engine.
- *
- * Exports the orchestrator, config parsing, storage, search,
- * extraction, graph, trust zones, and access layer.
- *
- * This package has ZERO OpenClaw imports — it can be consumed by
- * any host adapter (CLI, HTTP server, MCP server, etc.).
- *
+ * @remnic/core — framework-agnostic Remnic memory engine.
+ * Zero OpenClaw imports. Any host adapter can consume this package.
  */
-
 export { collapseWhitespace, displayWidth, graphemeUnits, padEndDisplay, truncateCodePointSafe, truncateGraphemeSafe } from "./whitespace.js";
+export * from "./context-summary.js";
+export * from "./active-context-transform.js";
 
 // ---------------------------------------------------------------------------
 // Plugin entry resolution