@semiont/jobs 0.5.26 → 0.5.28

package/dist/index.js

@@ -2,11 +2,11 @@ import { promises, mkdtempSync, writeFileSync, readFileSync, rmSync } from 'fs';
 import * as path from 'path';
 import { join } from 'path';
 import { jobId, deriveViews, reconcileSelector, GENERATABLE_MEDIA_TYPES, estimateTokens, chunkText, isObject, isString, getLocaleEnglishName } from '@semiont/core';
+import { withSpan } from '@semiont/observability';
 import { execFileSync } from 'child_process';
 import { tmpdir } from 'os';
 import { withinByteBudget, MAX_PDF_BYTES } from '@semiont/content';
 import '@semiont/event-sourcing';
-import '@semiont/observability';
 import '@semiont/sdk';
 import '@semiont/http-transport';
 
@@ -426,10 +426,18 @@ function isFailedJob(job) {
 function isCancelledJob(job) {
   return job.status === "cancelled";
 }
-
-// src/workers/inference-call.ts
 var INFERENCE_TIMEOUT_MS = 10 * 6e4;
-async function withTimeout(work, label) {
+var INFERENCE_HEARTBEAT_MS = 15e3;
+function spanned(client, kind, maxTokens, work) {
+  return withSpan(`inference:${kind}`, work, {
+    attrs: {
+      "inference.provider": client.type,
+      "inference.model": client.modelId,
+      "inference.max_tokens": maxTokens
+    }
+  });
+}
+async function withTimeout(work, label, onHeartbeat) {
   let timer;
   const timedOut = new Promise((_, reject) => {
     timer = setTimeout(() => {
@@ -439,6 +447,16 @@ async function withTimeout(work, label) {
     }, INFERENCE_TIMEOUT_MS);
     timer.unref?.();
   });
+  let heartbeat;
+  if (onHeartbeat) {
+    heartbeat = setInterval(() => {
+      try {
+        onHeartbeat();
+      } catch {
+      }
+    }, INFERENCE_HEARTBEAT_MS);
+    heartbeat.unref?.();
+  }
   try {
     return await Promise.race([work, timedOut]);
   } catch (err) {
@@ -447,19 +465,22 @@ async function withTimeout(work, label) {
     throw err;
   } finally {
     clearTimeout(timer);
+    if (heartbeat) clearInterval(heartbeat);
   }
 }
-function boundedGenerate(client, prompt, maxTokens, temperature) {
-  return withTimeout(
-    client.generateText(prompt, maxTokens, temperature),
-    `${client.type}:${client.modelId}`
-  );
+function boundedGenerateWithMetadata(client, prompt, maxTokens, temperature, onHeartbeat) {
+  return spanned(client, "text", maxTokens, () => withTimeout(
+    client.generateTextWithMetadata(prompt, maxTokens, temperature),
+    `${client.type}:${client.modelId}`,
+    onHeartbeat
+  ));
 }
-function boundedGenerateStructured(client, prompt, maxTokens, temperature, elementSchema) {
-  return withTimeout(
+function boundedGenerateStructured(client, prompt, maxTokens, temperature, elementSchema, onHeartbeat) {
+  return spanned(client, "structured", maxTokens, () => withTimeout(
     client.generateStructured(prompt, maxTokens, temperature, elementSchema),
-    `${client.type}:${client.modelId}`
-  );
+    `${client.type}:${client.modelId}`,
+    onHeartbeat
+  ));
 }
 
 // src/workers/detection/detection-chunking.ts
@@ -990,7 +1011,7 @@ function assertNotTruncated(response, motivation, chunk, totalChunks, outputBudg
     throw new Error(`${motivation} detection response truncated (max_tokens) on chunk ${chunk}/${totalChunks} despite the derived output budget of ${outputBudget} tokens \u2014 failing the job rather than under-reporting annotations.`);
   }
 }
-async function detectInChunks(client, content, buildPrompt, temperature, motivation, elementSchema, parse, onChunk) {
+async function detectInChunks(client, content, buildPrompt, temperature, motivation, elementSchema, parse, onActivity) {
   const limits = await client.limits();
   const scaffoldTokens = estimateTokens(buildPrompt(""));
   const { chunking, outputBudget } = deriveDetectionBudget(limits, scaffoldTokens);
@@ -1002,12 +1023,14 @@ async function detectInChunks(client, content, buildPrompt, temperature, motivat
       buildPrompt(chunks[i]),
       outputBudget,
       temperature,
-      elementSchema
+      elementSchema,
+      // Still alive, same position (a long single call is otherwise silent).
+      () => onActivity?.(i, chunks.length)
     );
     assertNotTruncated(response, motivation, i + 1, chunks.length, outputBudget);
     collected.push(...parse(response.items));
     if (i < chunks.length - 1) {
-      onChunk?.(i + 1, chunks.length);
+      onActivity?.(i + 1, chunks.length);
     }
   }
   return collected;
@@ -1021,7 +1044,7 @@ var AnnotationDetection = class {
    * (source-resource locale). See `types.ts` "Locale conventions" for the
    * full discussion.
    */
-  static async detectComments(content, client, instructions, tone, density, language, sourceLanguage, onChunk) {
+  static async detectComments(content, client, instructions, tone, density, language, sourceLanguage, onActivity) {
     return detectInChunks(
       client,
       content,
@@ -1030,7 +1053,7 @@ var AnnotationDetection = class {
       "comment",
       COMMENT_ELEMENT_SCHEMA,
       (items) => MotivationParsers.parseComments(items, content),
-      onChunk
+      onActivity
     );
   }
   /**
@@ -1040,7 +1063,7 @@ var AnnotationDetection = class {
    * applies, used in the prompt so the LLM analyzes non-English source
    * correctly.
    */
-  static async detectHighlights(content, client, instructions, density, sourceLanguage, onChunk) {
+  static async detectHighlights(content, client, instructions, density, sourceLanguage, onActivity) {
     return detectInChunks(
       client,
       content,
@@ -1049,7 +1072,7 @@ var AnnotationDetection = class {
       "highlight",
       HIGHLIGHT_ELEMENT_SCHEMA,
       (items) => MotivationParsers.parseHighlights(items, content),
-      onChunk
+      onActivity
     );
   }
   /**
@@ -1059,7 +1082,7 @@ var AnnotationDetection = class {
    * (annotation body locale). `sourceLanguage` is the locale of the content
    * being analyzed (source-resource locale).
    */
-  static async detectAssessments(content, client, instructions, tone, density, language, sourceLanguage, onChunk) {
+  static async detectAssessments(content, client, instructions, tone, density, language, sourceLanguage, onActivity) {
     return detectInChunks(
       client,
       content,
@@ -1068,7 +1091,7 @@ var AnnotationDetection = class {
       "assessment",
       ASSESSMENT_ELEMENT_SCHEMA,
       (items) => MotivationParsers.parseAssessments(items, content),
-      onChunk
+      onActivity
     );
   }
   /**
@@ -1083,7 +1106,7 @@ var AnnotationDetection = class {
    * identifiers, not LLM-generated text — so it's consumed at the body-stamp
    * site, not here.
    */
-  static async detectTags(content, client, schema, category, sourceLanguage, onChunk) {
+  static async detectTags(content, client, schema, category, sourceLanguage, onActivity) {
     const categoryInfo = schema.tags.find((t) => t.name === category);
     if (!categoryInfo) {
       throw new Error(`Invalid category "${category}" for schema ${schema.id}`);
@@ -1105,7 +1128,7 @@ var AnnotationDetection = class {
       "tag",
       TAG_ELEMENT_SCHEMA,
       (items) => MotivationParsers.parseTags(items),
-      onChunk
+      onActivity
     );
     return MotivationParsers.validateTagOffsets(parsedTags, content, category);
   }
@@ -1121,7 +1144,7 @@ var ENTITY_ELEMENT_SCHEMA = {
   required: ["exact", "entityType"],
   additionalProperties: false
 };
-async function extractEntities(exact, entityTypes, client, includeDescriptiveReferences, logger, sourceLanguage, onChunk) {
+async function extractEntities(exact, entityTypes, client, includeDescriptiveReferences, logger, sourceLanguage, onActivity) {
   const entityTypesDescription = entityTypes.map((et) => {
     if (typeof et === "string") {
       return et;
@@ -1188,7 +1211,10 @@ Example output:
       outputBudget,
       0.3,
       // Lower temperature for more consistent extraction
-      ENTITY_ELEMENT_SCHEMA
+      ENTITY_ELEMENT_SCHEMA,
+      // Still alive, same position: a long single call would otherwise emit
+      // nothing at all between start and finish.
+      () => onActivity?.(i, chunks.length)
     );
     logger.debug("Got entity extraction response", {
       chunk: i + 1,
@@ -1213,7 +1239,7 @@ Example output:
       }
     }
     if (i < chunks.length - 1) {
-      onChunk?.(i + 1, chunks.length);
+      onActivity?.(i + 1, chunks.length);
     }
   }
   return collected;
@@ -1227,6 +1253,7 @@ var SEMANTIC_MATCH_CHARS = 240;
 function idLabel(resourceId, annotationId) {
   return `[${resourceId}${annotationId ? `/${annotationId}` : ""}]`;
 }
+var DEFAULT_MAX_TOKENS = 500;
 async function generateResourceFromTopic(topic, entityTypes, client, logger, userPrompt, locale, context, temperature, maxTokens, sourceLanguage, outputMediaType = "text/markdown", task = "resource", structure, cite = false, repair) {
   logger.debug("Generating resource from topic", {
     topicPreview: topic.substring(0, 100),
@@ -1242,7 +1269,7 @@ async function generateResourceFromTopic(topic, entityTypes, client, logger, use
     structure
   });
   const finalTemperature = temperature ?? 0.7;
-  const finalMaxTokens = maxTokens ?? 500;
+  const finalMaxTokens = maxTokens ?? DEFAULT_MAX_TOKENS;
   const languageInstruction = locale && locale !== "en" ? `
 
 IMPORTANT: Write the entire resource in ${getLanguageName(locale)}.` : "";
@@ -1269,6 +1296,9 @@ The source resource and embedded context are in ${getLanguageName(sourceLanguage
           parts.push(`- ${label}: ${bodyItem.value}`);
         }
       }
+      if (focus.userHint) {
+        parts.push(`- User hint (steers what to generate): ${focus.userHint}`);
+      }
       annotationSection = `
 
 Annotation context:
@@ -1427,16 +1457,16 @@ ${formatRequirements}`;
     temperature: finalTemperature,
     maxTokens: finalMaxTokens
   });
-  const response = await boundedGenerate(client, prompt, finalMaxTokens, finalTemperature);
-  logger.debug("Got response from inference", { responseLength: response.length });
-  const result = parseResponse(response);
+  const response = await boundedGenerateWithMetadata(client, prompt, finalMaxTokens, finalTemperature);
+  logger.debug("Got response from inference", { responseLength: response.text.length, stopReason: response.stopReason });
+  const result = parseResponse(response.text);
   logger.debug("Parsed response", {
     hasTitle: !!result.title,
     titleLength: result.title?.length,
     hasContent: !!result.content,
     contentLength: result.content?.length
   });
-  return result;
+  return { ...result, truncated: response.stopReason === "max_tokens" };
 }
 var PINNED_CREATION_TIMESTAMP = 17e8;
 var MAX_COMPILE_REPAIRS = 2;
@@ -1557,30 +1587,39 @@ function dedupeAnnotations(annotations) {
   return out;
 }
 async function processHighlightJob(content, inferenceClient, params, buildAnnotation, onProgress) {
-  onProgress(10, "Loading resource...", "analyzing");
-  onProgress(30, "Analyzing text...", "analyzing");
+  const echo = detectionEcho(params);
+  onProgress(10, { code: "loading" }, echo);
+  onProgress(30, { code: "analyzing" }, echo);
   const highlights = await AnnotationDetection.detectHighlights(
     content,
     inferenceClient,
     params.instructions,
     params.density,
     params.sourceLanguage,
-    // Chunk-boundary heartbeat (liveness): interpolate within the 30–60 band.
-    (completed, total) => onProgress(30 + Math.round(completed / total * 30), "Analyzing text...", "analyzing")
+    // Liveness (chunk boundaries + in-flight heartbeat): 30–60 band.
+    (completed, total) => onProgress(30 + Math.round(completed / total * 30), { code: "analyzing" }, echo)
   );
-  onProgress(60, `Creating ${highlights.length} annotations...`, "creating");
+  onProgress(60, { code: "creating-annotations", count: highlights.length }, echo);
   const annotations = dedupeAnnotations(highlights.map(
     (h) => buildAnnotation("highlighting", h)
   ));
-  onProgress(100, `Complete! Created ${annotations.length} highlights`, "creating");
+  onProgress(100, { code: "complete-created", count: annotations.length, kind: "highlight" }, echo);
   return {
     annotations,
-    result: { highlightsFound: highlights.length, highlightsCreated: annotations.length }
+    result: { kind: "highlight-annotation", highlightsFound: highlights.length, highlightsCreated: annotations.length }
   };
 }
+function detectionEcho(p) {
+  const requestParams = [];
+  if (p.instructions?.trim()) requestParams.push({ label: "instructions", value: p.instructions.trim() });
+  if (p.tone?.trim()) requestParams.push({ label: "tone", value: p.tone.trim() });
+  if (p.density !== void 0) requestParams.push({ label: "density", value: String(p.density) });
+  return requestParams.length > 0 ? { requestParams } : {};
+}
 async function processCommentJob(content, inferenceClient, params, buildAnnotation, onProgress) {
-  onProgress(10, "Loading resource...", "analyzing");
-  onProgress(30, "Analyzing text...", "analyzing");
+  const echo = detectionEcho(params);
+  onProgress(10, { code: "loading" }, echo);
+  onProgress(30, { code: "analyzing" }, echo);
   const comments = await AnnotationDetection.detectComments(
     content,
     inferenceClient,
@@ -1589,10 +1628,10 @@ async function processCommentJob(content, inferenceClient, params, buildAnnotati
     params.density,
     params.language,
     params.sourceLanguage,
-    // Chunk-boundary heartbeat (liveness): interpolate within the 30–60 band.
-    (completed, total) => onProgress(30 + Math.round(completed / total * 30), "Analyzing text...", "analyzing")
+    // Liveness (chunk boundaries + in-flight heartbeat): 30–60 band.
+    (completed, total) => onProgress(30 + Math.round(completed / total * 30), { code: "analyzing" }, echo)
   );
-  onProgress(60, `Creating ${comments.length} annotations...`, "creating");
+  onProgress(60, { code: "creating-annotations", count: comments.length }, echo);
   const bodyLanguage = params.language ?? "en";
   const annotations = dedupeAnnotations(comments.map(
     (c) => (
@@ -1604,15 +1643,16 @@ async function processCommentJob(content, inferenceClient, params, buildAnnotati
       ])
     )
   ));
-  onProgress(100, `Complete! Created ${annotations.length} comments`, "creating");
+  onProgress(100, { code: "complete-created", count: annotations.length, kind: "comment" }, echo);
   return {
     annotations,
-    result: { commentsFound: comments.length, commentsCreated: annotations.length }
+    result: { kind: "comment-annotation", commentsFound: comments.length, commentsCreated: annotations.length }
   };
 }
 async function processAssessmentJob(content, inferenceClient, params, buildAnnotation, onProgress) {
-  onProgress(10, "Loading resource...", "analyzing");
-  onProgress(30, "Analyzing text...", "analyzing");
+  const echo = detectionEcho(params);
+  onProgress(10, { code: "loading" }, echo);
+  onProgress(30, { code: "analyzing" }, echo);
   const assessments = await AnnotationDetection.detectAssessments(
     content,
     inferenceClient,
@@ -1621,10 +1661,10 @@ async function processAssessmentJob(content, inferenceClient, params, buildAnnot
     params.density,
     params.language,
     params.sourceLanguage,
-    // Chunk-boundary heartbeat (liveness): interpolate within the 30–60 band.
-    (completed, total) => onProgress(30 + Math.round(completed / total * 30), "Analyzing text...", "analyzing")
+    // Liveness (chunk boundaries + in-flight heartbeat): 30–60 band.
+    (completed, total) => onProgress(30 + Math.round(completed / total * 30), { code: "analyzing" }, echo)
   );
-  onProgress(60, `Creating ${assessments.length} annotations...`, "creating");
+  onProgress(60, { code: "creating-annotations", count: assessments.length }, echo);
   const bodyLanguage = params.language ?? "en";
   const annotations = dedupeAnnotations(assessments.map(
     (a) => (
@@ -1643,33 +1683,35 @@ async function processAssessmentJob(content, inferenceClient, params, buildAnnot
       })
     )
   ));
-  onProgress(100, `Complete! Created ${annotations.length} assessments`, "creating");
+  onProgress(100, { code: "complete-created", count: annotations.length, kind: "assessment" }, echo);
   return {
     annotations,
-    result: { assessmentsFound: assessments.length, assessmentsCreated: annotations.length }
+    result: { kind: "assessment-annotation", assessmentsFound: assessments.length, assessmentsCreated: annotations.length }
   };
 }
 async function processReferenceJob(content, inferenceClient, params, buildAnnotation, onProgress, logger) {
   const entityTypeNames = params.entityTypes.map(String);
-  const requestParams = [{ label: "Entity types", value: entityTypeNames.join(", ") }];
-  const completedEntityTypes = [];
+  const requestParams = [{ label: "entity-types", value: entityTypeNames.join(", ") }];
+  const completedItems = [];
   let totalFound = 0;
   let totalEmitted = 0;
   let errors = 0;
   const allAnnotations = [];
-  onProgress(10, "Loading resource...", "analyzing", { requestParams });
+  onProgress(10, { code: "loading" }, { requestParams });
   const bodyLanguage = params.language ?? "en";
   for (let i = 0; i < entityTypeNames.length; i++) {
     const entityTypeName = entityTypeNames[i];
     if (!entityTypeName) continue;
     const pct = 20 + Math.round(i / entityTypeNames.length * 60);
-    onProgress(pct, `Detecting ${entityTypeName} entities...`, "analyzing", {
-      currentEntityType: entityTypeName,
-      processedEntityTypes: i,
-      totalEntityTypes: entityTypeNames.length,
+    onProgress(pct, { code: "detecting-entities", entityType: entityTypeName }, {
+      // One vocabulary for "what is in flight" (CLEAN-PROGRESS D2): the entity
+      // type is KB data, `kind` is the code the client localizes around it.
+      current: { kind: "entity-type", value: entityTypeName },
+      processed: i,
+      total: entityTypeNames.length,
       entitiesFound: totalFound,
       entitiesEmitted: totalEmitted,
-      completedEntityTypes: [...completedEntityTypes],
+      completedItems: [...completedItems],
       requestParams
     });
     const extractedEntities = await extractEntities(
@@ -1679,25 +1721,28 @@ async function processReferenceJob(content, inferenceClient, params, buildAnnota
       params.includeDescriptiveReferences ?? false,
       logger,
       params.sourceLanguage,
-      // Chunk-boundary heartbeat: progress is the worker's liveness signal
-      // (stall watchdog + backend janitor), so multi-chunk extraction must
-      // emit between inference calls. Percentage interpolates within this
-      // entity type's band of the 20–80 range.
+      // Liveness: fires at chunk boundaries AND every ~15 s while a single
+      // inference call is in flight (DETECTION-HEARTBEAT). Progress feeds the
+      // stall watchdog, the janitor, AND the client's inter-emission timeout,
+      // so a long single-chunk call must not be silent. Percentage
+      // interpolates within this entity type's band of the 20–80 range; a
+      // heartbeat repeats the current position rather than inventing an
+      // advance.
       (completed, total) => {
         const interpolated = 20 + Math.round((i + completed / total) / entityTypeNames.length * 60);
-        onProgress(interpolated, `Detecting ${entityTypeName} entities...`, "analyzing", {
-          currentEntityType: entityTypeName,
-          processedEntityTypes: i,
-          totalEntityTypes: entityTypeNames.length,
+        onProgress(interpolated, { code: "detecting-entities", entityType: entityTypeName }, {
+          current: { kind: "entity-type", value: entityTypeName },
+          processed: i,
+          total: entityTypeNames.length,
           entitiesFound: totalFound,
           entitiesEmitted: totalEmitted,
-          completedEntityTypes: [...completedEntityTypes],
+          completedItems: [...completedItems],
           requestParams
         });
       }
     );
     totalFound += extractedEntities.length;
-    completedEntityTypes.push({ entityType: entityTypeName, foundCount: extractedEntities.length });
+    completedItems.push({ value: entityTypeName, foundCount: extractedEntities.length });
     const unresolvedBody = [
       { type: "TextualBody", value: entityTypeName, purpose: "tagging", format: "text/plain", language: bodyLanguage }
     ];
@@ -1728,36 +1773,49 @@ async function processReferenceJob(content, inferenceClient, params, buildAnnota
     }
   }
   const annotations = dedupeAnnotations(allAnnotations);
-  onProgress(100, `Complete! Created ${annotations.length} references`, "creating");
+  onProgress(100, { code: "complete-created", count: annotations.length, kind: "reference" }, { requestParams });
   return {
     annotations,
-    result: { totalFound, totalEmitted: annotations.length, errors }
+    result: { kind: "reference-annotation", totalFound, totalEmitted: annotations.length, errors }
   };
 }
 async function processTagJob(content, inferenceClient, params, buildAnnotation, onProgress) {
-  onProgress(10, "Loading resource...", "analyzing");
-  onProgress(30, "Analyzing text for tags...", "analyzing");
+  onProgress(10, { code: "loading" });
+  onProgress(30, { code: "analyzing-tags" });
   const allTags = [];
+  const completedItems = [];
   for (let c = 0; c < params.categories.length; c++) {
     const category = params.categories[c];
+    const position = () => ({
+      current: { kind: "category", value: category },
+      processed: c,
+      total: params.categories.length,
+      completedItems: [...completedItems]
+    });
+    onProgress(
+      30 + Math.round(c / params.categories.length * 30),
+      { code: "analyzing-tags" },
+      position()
+    );
     const categoryTags = await AnnotationDetection.detectTags(
       content,
       inferenceClient,
       params.schema,
       category,
       params.sourceLanguage,
-      // Chunk-boundary heartbeat (liveness): interpolate within this
-      // category's slice of the 30–60 band.
+      // Liveness (chunk boundaries + in-flight heartbeat): this category's
+      // slice of the 30–60 band.
       (completed, total) => onProgress(
         30 + Math.round((c + completed / total) / params.categories.length * 30),
-        "Analyzing text for tags...",
-        "analyzing"
+        { code: "analyzing-tags" },
+        position()
       )
     );
+    completedItems.push({ value: category, foundCount: categoryTags.length });
     allTags.push(...categoryTags);
   }
   const tags = allTags;
-  onProgress(60, `Creating ${tags.length} tag annotations...`, "creating");
+  onProgress(60, { code: "creating-tag-annotations", count: tags.length });
   const bodyLanguage = params.language ?? "en";
   const annotations = dedupeAnnotations(tags.map((t) => {
     const category = t.category ?? "unknown";
@@ -1772,10 +1830,10 @@ async function processTagJob(content, inferenceClient, params, buildAnnotation,
     const category = Array.isArray(body) && typeof body[0]?.value === "string" ? body[0].value : "unknown";
     byCategory[category] = (byCategory[category] ?? 0) + 1;
   }
-  onProgress(100, `Complete! Created ${annotations.length} tags`, "creating");
+  onProgress(100, { code: "complete-created", count: annotations.length, kind: "tag" });
   return {
     annotations,
-    result: { tagsFound: tags.length, tagsCreated: annotations.length, byCategory }
+    result: { kind: "tag-annotation", tagsFound: tags.length, tagsCreated: annotations.length, byCategory }
   };
 }
 function assertWithinOutputBudget(byteLength) {
@@ -1795,7 +1853,7 @@ async function processGenerationJob(inferenceClient, params, onProgress, logger)
   const title = params.title ?? "Untitled";
   const entityTypes = (params.entityTypes ?? []).map(String);
   if (outputMediaType === "application/pdf") {
-    onProgress(5, "Generating resource...", "generating");
+    onProgress(5, { code: "generating-resource" });
     const validIds = params.cite === true ? collectContextResourceIds(params.context) : null;
     let generated2 = await generateResourceFromTopic(
       title,
@@ -1822,7 +1880,17 @@ async function processGenerationJob(inferenceClient, params, onProgress, logger)
     }
     let compiled = compileTypst(source);
     let repairs = 0;
-    while ("error" in compiled && repairs < MAX_COMPILE_REPAIRS) {
+    while ("error" in compiled) {
+      if (generated2.truncated) {
+        throw new Error(
+          `Generation stopped at the maxTokens ceiling (${params.maxTokens ?? DEFAULT_MAX_TOKENS} tokens) and the cut-off Typst source does not compile \u2014 repair cannot help; raise maxTokens. Compile error: ${compiled.error}`
+        );
+      }
+      if (repairs >= MAX_COMPILE_REPAIRS) {
+        throw new Error(
+          `Typst compilation failed after ${MAX_COMPILE_REPAIRS} repair attempts: ${compiled.error}`
+        );
+      }
       repairs++;
       logger.warn("Typst compile failed \u2014 feeding the error back for repair", {
         attempt: repairs,
@@ -1854,25 +1922,23 @@ async function processGenerationJob(inferenceClient, params, onProgress, logger)
       }
       compiled = compileTypst(source);
     }
-    if ("error" in compiled) {
-      throw new Error(
-        `Typst compilation failed after ${MAX_COMPILE_REPAIRS} repair attempts: ${compiled.error}`
-      );
-    }
     assertWithinOutputBudget(compiled.pdf.byteLength);
-    onProgress(95, "Creating resource...", "creating");
+    onProgress(95, { code: "creating-resource" });
+    onProgress(100, { code: "complete-generated", truncated: generated2.truncated });
     return {
       content: compiled.pdf,
-      title: generated2.title ?? title,
+      title,
       format: outputMediaType,
       citations: citations2,
       result: {
+        kind: "generation",
         resourceId: "",
-        resourceName: generated2.title ?? title
+        resourceName: title,
+        truncated: generated2.truncated
       }
     };
   }
-  onProgress(5, "Generating resource...", "generating");
+  onProgress(5, { code: "generating-resource" });
   const generated = await generateResourceFromTopic(
     title,
     entityTypes,
@@ -1896,17 +1962,20 @@ async function processGenerationJob(inferenceClient, params, onProgress, logger)
     content = resolved.content;
     citations = resolved.citations;
   }
-  onProgress(95, "Creating resource...", "creating");
+  onProgress(95, { code: "creating-resource" });
   const artifact = new TextEncoder().encode(content);
   assertWithinOutputBudget(artifact.byteLength);
+  onProgress(100, { code: "complete-generated", truncated: generated.truncated });
   return {
     content: artifact,
-    title: generated.title ?? title,
+    title,
     format: outputMediaType,
     citations,
     result: {
+      kind: "generation",
       resourceId: "",
-      resourceName: generated.title ?? title
+      resourceName: title,
+      truncated: generated.truncated
     }
   };
 }