feat: refine metadata catalog workflows

backend/src/catalog/model-completer.ts

@@ -4,7 +4,7 @@ import type { ResolvedMetadataGenerationModel } from "./metadata-generation-mode
 
 const MAX_HELPER_OUTPUT_BYTES = 64 * 1024;
 const helperOutputSchema = z.discriminatedUnion("ok", [
-  z.object({ ok: z.literal(true), content: z.string() }).strict(),
+  z.object({ ok: z.literal(true), content: z.string(), usage: z.object({ input: z.number().int().nonnegative(), cacheRead: z.number().int().nonnegative(), output: z.number().int().nonnegative() }).strict().optional() }).strict(),
   z.object({ ok: z.literal(false), error: z.literal("provider_failure") }).strict(),
 ]);
 
@@ -18,10 +18,12 @@ export interface ModelCompletionRequest {
   messages: readonly ModelCompletionMessage[];
   signal: AbortSignal;
 }
+export interface ModelCompletionUsage { input: number; cacheRead: number; output: number; }
+export interface ModelCompletionResult { content: string; usage: ModelCompletionUsage; }
 
 /** The provider boundary used by Description Generation. */
 export interface ModelCompleter {
-  complete(request: ModelCompletionRequest): Promise<string>;
+  complete(request: ModelCompletionRequest): Promise<string | ModelCompletionResult>;
 }
 
 export class ModelCompletionProviderError extends Error {
@@ -47,7 +49,7 @@ export class PythonModelCompleter implements ModelCompleter {
     terminationGraceMs?: number;
   }) {}
 
-  async complete(request: ModelCompletionRequest): Promise<string> {
+  async complete(request: ModelCompletionRequest): Promise<ModelCompletionResult> {
     if (request.signal.aborted) throw new ModelCompletionCancelledError();
     const payload = {
       model: `${request.model.provider}/${request.model.model}`,
@@ -62,7 +64,7 @@ export class PythonModelCompleter implements ModelCompleter {
       ...(request.model.disableThinking === true ? { disable_thinking: true } : {}),
     };
 
-    return await new Promise<string>((resolve, reject) => {
+    return await new Promise<ModelCompletionResult>((resolve, reject) => {
       const child = spawn(
         this.options.pythonExecutable,
         ["-m", this.options.helperModule ?? "tht.internal.litellm_completion"],
@@ -135,7 +137,7 @@ export class PythonModelCompleter implements ModelCompleter {
           if (!output.ok) return fail();
           settled = true;
           cleanup();
-          resolve(output.content);
+          resolve({ content: output.content, usage: output.usage ?? { input: 0, cacheRead: 0, output: 0 } });
         } catch {
           fail();
         }