feat(ai): recorder redaction/truncateRow seam + never-throw LlmCallDbRecorder

Task 2: prove the redact seam (existing wiring confirmed via test) + add
truncateRow helper that caps llmRequest/llmResponse strings to maxChars —
composable into a redact fn to bound trace-row size.

Task 3: LlmCallDbRecorder now accepts an optional opts.onError callback and
wraps om.create in try/catch; default onError is a no-op so telemetry can
never surface into the call path. LlmCallDbRecorderOpts exported from index.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/runtime-ts/src/index.ts

@@ -37,5 +37,5 @@ export {
 // Format is re-exported here so callers of recordLlmCall can import it from a
 // single location rather than reaching into @metaobjectsdev/render directly.
 export { Format } from "@metaobjectsdev/render";
-export { LlmCallDbRecorder, NullRecorder, recordLlmCall, buildLlmCallRow, persistLlmCallRow } from "./llm-recorder.js";
-export type { LlmRecorder, LlmCallRow, LlmCallInput, RecordLlmCallOptions, RecordLlmCallResult } from "./llm-recorder.js";
+export { LlmCallDbRecorder, NullRecorder, recordLlmCall, buildLlmCallRow, persistLlmCallRow, truncateRow } from "./llm-recorder.js";
+export type { LlmRecorder, LlmCallRow, LlmCallInput, RecordLlmCallOptions, RecordLlmCallResult, LlmCallDbRecorderOpts } from "./llm-recorder.js";

server/typescript/packages/runtime-ts/src/llm-recorder.ts

@@ -38,17 +38,28 @@ export class NullRecorder implements LlmRecorder {
 // LlmCallDbRecorder — persists via ObjectManager
 // =============================================================================
 
+export interface LlmCallDbRecorderOpts {
+  /** Called when om.create throws. Default: swallow. Telemetry never breaks the app. */
+  onError?: (error: unknown) => void;
+}
+
 export class LlmCallDbRecorder implements LlmRecorder {
   private readonly om: ObjectManager;
   private readonly entityName: string;
+  private readonly onError: (error: unknown) => void;
 
-  constructor(om: ObjectManager, entityName: string) {
+  constructor(om: ObjectManager, entityName: string, opts?: LlmCallDbRecorderOpts) {
     this.om = om;
     this.entityName = entityName;
+    this.onError = opts?.onError ?? (() => {});
   }
 
   async record(call: LlmCallRow): Promise<void> {
-    await this.om.create(this.entityName, call);
+    try {
+      await this.om.create(this.entityName, call);
+    } catch (err) {
+      this.onError(err);
+    }
   }
 }
 
@@ -132,6 +143,15 @@ export async function persistLlmCallRow(
   await recorder.record(opts?.redact ? opts.redact(row) : row);
 }
 
+/** Cap the raw `llmRequest`/`llmResponse` string columns to `maxChars`.
+ *  Adopters compose this into a `redact` to bound trace-row size. Only the two
+ *  raw string columns are touched; all other fields pass through unchanged. */
+export function truncateRow(row: LlmCallRow, maxChars: number): LlmCallRow {
+  const cap = (v: unknown): unknown =>
+    typeof v === "string" && v.length > maxChars ? v.slice(0, maxChars) : v;
+  return { ...row, llmRequest: cap(row.llmRequest), llmResponse: cap(row.llmResponse) };
+}
+
 /** Persist one base trace row (envelope + raw I/O). Generic — does not extract. */
 export async function recordLlmCall(
   input: LlmCallInput,

server/typescript/packages/runtime-ts/test/llm-recorder.test.ts

@@ -260,6 +260,62 @@ describe("recordLlmCall envelope fields — parentSpanId + sessionId", () => {
   });
 });
 
+// =============================================================================
+// Task 2 (P0) — redaction seam + truncateRow helper
+// =============================================================================
+
+import { truncateRow } from "../src/llm-recorder.js";
+
+class CaptureRedact extends NullRecorder {
+  last: LlmCallRow | null = null;
+  override async record(c: LlmCallRow): Promise<void> { this.last = c; }
+}
+
+describe("recorder redaction + truncation", () => {
+  test("redact is applied before persist", async () => {
+    const rec = new CaptureRedact();
+    await recordLlmCall(
+      { spanId:"s", traceId:"t", callType:"X", startedAt:"2026-06-06T00:00:00Z",
+        llmRequest:{ secret:"sk-123" }, llmResponseText:"{}", status:"ok", errorDetail:null },
+      { recorder: rec, redact: (row) => ({ ...row, llmRequest: "[redacted]" }) },
+    );
+    expect(rec.last?.llmRequest).toBe("[redacted]");
+  });
+
+  test("truncateRow caps the raw llmRequest/llmResponse strings", () => {
+    const row: LlmCallRow = { llmRequest: "0123456789abcdef", llmResponse: "xxxxxxxxxx", callType: "X" };
+    const capped = truncateRow(row, 5);
+    expect(capped.llmRequest).toBe("01234");
+    expect(capped.llmResponse).toBe("xxxxx");
+    expect(capped.callType).toBe("X"); // non-raw fields untouched
+  });
+});
+
+// =============================================================================
+// Task 3 (P0) — LlmCallDbRecorder never-throw
+// =============================================================================
+
+import { LlmCallDbRecorder as LlmCallDbRecorderImport } from "../src/llm-recorder.js";
+import type { ObjectManager as ObjectManagerType } from "../src/object-manager.js";
+
+describe("LlmCallDbRecorder never-throw", () => {
+  test("swallows om.create failure via onError, never throws", async () => {
+    const om = { create: async () => { throw new Error("db down"); } } as unknown as ObjectManagerType;
+    const errs: unknown[] = [];
+    const rec = new LlmCallDbRecorderImport(om, "TraceCall", { onError: (e) => errs.push(e) });
+    await rec.record({ spanId: "s" }); // must NOT throw
+    expect(errs.length).toBe(1);
+    expect(String((errs[0] as Error).message)).toContain("db down");
+  });
+
+  test("default onError swallows (no throw, no crash)", async () => {
+    const om = { create: async () => { throw new Error("x"); } } as unknown as ObjectManagerType;
+    const rec = new LlmCallDbRecorderImport(om, "TraceCall");
+    await rec.record({ spanId: "s" }); // must resolve, not reject
+    expect(true).toBe(true);
+  });
+});
+
 // =============================================================================
 // Task 1 (P0) — buildLlmCallRow: base-row factory (exactly LlmCallBase fields)
 // =============================================================================