refactor(ai): factor runLlmCall (call, no persist); callLlm persists the generic base row

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

Author: dmealing

server/typescript/packages/ai-runtime/src/call-loop.ts

@@ -1,59 +1,57 @@
 import {
-  recordLlmCall,
+  buildLlmCallRow,
+  persistLlmCallRow,
   type LlmRecorder,
   type LlmCallInput,
-  type RecordLlmCallOptions,
+  type LlmCallRow,
   type RecordLlmCallResult,
-  type Format,
 } from "@metaobjectsdev/runtime-ts";
-import type { MetaObject } from "@metaobjectsdev/metadata";
 import {
   systemClock,
   uuidIds,
   type Clock,
   type IdGen,
   type LlmClient,
   type LlmRequest,
+  type LlmCompletion,
 } from "./client.js";
 import { builtinCost, type CostFn } from "./cost.js";
 
-export interface CallLlmInput {
-  /** Discriminator / call identity; defaults to the generated entity name. */
+export interface RunLlmCallInput {
+  /** Discriminator / call identity. */
   callType: string;
-  /** The typed request VO, passed through for call-site traceability. (Not
-   *  persisted directly — `request` is what gets logged as llmRequest.) */
-  payload: unknown;
-  /** What we send to the client (already-rendered prompt + model + params). */
+  /** Already-rendered request sent to the client. */
   request: LlmRequest;
   /** Existing trace to attach to; a new trace id is generated when absent. */
   traceId?: string;
-  /** Parent span id; absent → this is a root span. */
   parentSpanId?: string;
-  /** Logical session/conversation id. */
   sessionId?: string;
 }
 
-export interface CallLlmDeps {
+export interface RunLlmCallDeps {
   client: LlmClient;
-  recorder: LlmRecorder;
-  /** MetaObject for the response VO (passed to extract, same as recordLlmCall). */
-  responseMo: MetaObject;
-  format?: Format;
   cost?: CostFn;
   clock?: Clock;
   ids?: IdGen;
 }
 
+export interface RunLlmCallResult {
+  /** Ready-to-persist BASE recorder input (envelope + raw I/O + status). */
+  input: LlmCallInput;
+  /** Provider completion, or undefined if the client threw. */
+  completion?: LlmCompletion;
+}
+
 /**
- * CALL → PARSE → WRITE. The caller supplies the already-rendered prompt in
- * `input.request.prompt`; callLlm performs the CALL, computes latency/cost/ids,
- * then delegates PARSE+WRITE to recordLlmCall. Finally-style: a client throw
- * still writes an error row and never rethrows into the caller.
+ * Perform the LLM CALL: generate ids, time it, call the client (never-throw),
+ * compute cost. Returns a ready base LlmCallInput + the completion. Does NOT
+ * persist and does NOT extract — callers do that (callLlm persists the base row;
+ * the generated call<Entity> additionally extracts + writes typed voRequest/voResponse).
  */
-export async function callLlm(
-  input: CallLlmInput,
-  deps: CallLlmDeps,
-): Promise<RecordLlmCallResult> {
+export async function runLlmCall(
+  input: RunLlmCallInput,
+  deps: RunLlmCallDeps,
+): Promise<RunLlmCallResult> {
   const clock = deps.clock ?? systemClock;
   const ids = deps.ids ?? uuidIds;
   const cost = deps.cost ?? builtinCost;
@@ -63,63 +61,64 @@ export async function callLlm(
   const t0 = clock.now();
   const startedAt = new Date(t0).toISOString();
 
-  let completion: Awaited<ReturnType<LlmClient["complete"]>>;
+  let completion: LlmCompletion | undefined;
+  let status: "ok" | "error" = "ok";
+  let errorDetail: string | null = null;
   try {
     completion = await deps.client.complete(input.request);
   } catch (err) {
-    const errorDetail = err instanceof Error ? err.message : String(err);
-    // Hand-built error row: the client never returned, so there is no response
-    // to extract — we cannot route through recordLlmCall. Its column set mirrors
-    // recordLlmCall's row (same keys, null-valued where the call produced nothing).
-    const row = {
-      spanId,
-      traceId,
-      parentSpanId: input.parentSpanId ?? null,
-      sessionId: input.sessionId ?? null,
-      callType: input.callType,
-      requestModel: input.request.model,
-      responseModel: null,
-      inputTokens: null,
-      outputTokens: null,
-      costMinor: null,
-      latencyMs: clock.now() - t0,
-      finishReason: null,
-      status: "error" as const,
-      errorDetail,
-      startedAt,
-      llmRequest: JSON.stringify(input.request),
-      voResponse: null,
-    };
-    await deps.recorder.record(row);
-    return { voResponse: null, status: "error", errorDetail };
+    status = "error";
+    errorDetail = err instanceof Error ? err.message : String(err);
   }
+  const latencyMs = clock.now() - t0;
 
-  // Build the recordLlmCall input with only the optional fields that are
-  // actually present — `exactOptionalPropertyTypes` forbids assigning an
-  // explicit `undefined` to an optional `T?` property.
+  // exactOptionalPropertyTypes: assign optionals only when defined.
   const recInput: LlmCallInput = {
     spanId,
     traceId,
     callType: input.callType,
     startedAt,
+    latencyMs,
     requestModel: input.request.model,
-    latencyMs: clock.now() - t0,
-    llmRequest: completion.request ?? input.request,
-    llmResponseText: completion.body,
+    llmRequest: completion?.request ?? input.request,
+    llmResponseText: completion?.body ?? "",
+    status,
+    errorDetail,
   };
+  if (input.request.system !== undefined) recInput.system = input.request.system;
   if (input.parentSpanId !== undefined) recInput.parentSpanId = input.parentSpanId;
   if (input.sessionId !== undefined) recInput.sessionId = input.sessionId;
-  if (completion.model !== undefined) recInput.responseModel = completion.model;
-  if (completion.usage?.inputTokens !== undefined) recInput.inputTokens = completion.usage.inputTokens;
-  if (completion.usage?.outputTokens !== undefined) recInput.outputTokens = completion.usage.outputTokens;
-  const costMinor = cost(completion.model ?? input.request.model, completion.usage);
-  if (costMinor !== null) recInput.costMinor = costMinor;
-  if (completion.finishReason !== undefined) recInput.finishReason = completion.finishReason;
+  if (completion?.model !== undefined) recInput.responseModel = completion.model;
+  if (completion?.usage?.inputTokens !== undefined) recInput.inputTokens = completion.usage.inputTokens;
+  if (completion?.usage?.outputTokens !== undefined) recInput.outputTokens = completion.usage.outputTokens;
+  if (completion?.finishReason !== undefined) recInput.finishReason = completion.finishReason;
+  if (completion !== undefined) {
+    const c = cost(completion.model ?? input.request.model, completion.usage);
+    if (c !== null) recInput.costMinor = c;
+  }
 
-  const recOpts: RecordLlmCallOptions = {
-    recorder: deps.recorder,
-    responseMo: deps.responseMo,
-  };
-  if (deps.format !== undefined) recOpts.format = deps.format;
-  return recordLlmCall(recInput, recOpts);
+  return completion !== undefined ? { input: recInput, completion } : { input: recInput };
+}
+
+export interface CallLlmDeps extends RunLlmCallDeps {
+  recorder: LlmRecorder;
+  redact?: (row: LlmCallRow) => LlmCallRow;
+}
+
+/**
+ * Generic loop: CALL (runLlmCall) → persist the BASE row. No extract, no typed
+ * voRequest/voResponse (that's the generated call<Entity>). Finally-style: a
+ * client throw still persists an error row and never rethrows.
+ */
+export async function callLlm(
+  input: RunLlmCallInput,
+  deps: CallLlmDeps,
+): Promise<RecordLlmCallResult> {
+  const { input: recInput } = await runLlmCall(input, deps);
+  await persistLlmCallRow(
+    deps.recorder,
+    buildLlmCallRow(recInput),
+    deps.redact ? { redact: deps.redact } : undefined,
+  );
+  return { status: recInput.status, errorDetail: recInput.errorDetail };
 }

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

@@ -14,6 +14,13 @@ export {
 
 export { builtinCost, type CostFn } from "./cost.js";
 
-export { callLlm, type CallLlmInput, type CallLlmDeps } from "./call-loop.js";
+export {
+  callLlm,
+  runLlmCall,
+  type CallLlmDeps,
+  type RunLlmCallInput,
+  type RunLlmCallDeps,
+  type RunLlmCallResult,
+} from "./call-loop.js";
 
 export { CompositeRecorder, type CompositeRecorderOpts } from "./composite.js";