@semiont/jobs 0.4.19 → 0.4.21

package/dist/worker-main.js

@@ -0,0 +1,1646 @@
+import { InMemorySessionStorage, setStoredSession, SemiontSession, createJobClaimAdapter, validateAndCorrectOffsets, getLocaleEnglishName } from '@semiont/api-client';
+import { createTomlConfigLoader, RESOURCE_BROADCAST_TYPES, didToAgent } from '@semiont/core';
+import { deriveStorageUri } from '@semiont/content';
+import { generateAnnotationId } from '@semiont/event-sourcing';
+import { createInferenceClient } from '@semiont/inference';
+import { createServer } from 'http';
+import { existsSync, readFileSync } from 'fs';
+import { homedir, hostname } from 'os';
+import { join } from 'path';
+import winston from 'winston';
+
+// src/worker-process.ts
+
+// src/workers/detection/motivation-prompts.ts
+var MotivationPrompts = class {
+  /**
+   * Build a prompt for detecting comment-worthy passages
+   *
+   * @param content - The text content to analyze (will be truncated to 8000 chars)
+   * @param instructions - Optional user-provided instructions
+   * @param tone - Optional tone guidance (e.g., "academic", "conversational")
+   * @param density - Optional target number of comments per 2000 words
+   * @returns Formatted prompt string
+   */
+  static buildCommentPrompt(content, instructions, tone, density) {
+    let prompt;
+    if (instructions) {
+      const toneGuidance = tone ? ` Use a ${tone} tone.` : "";
+      const densityGuidance = density ? `
+
+Aim for approximately ${density} comments per 2000 words of text.` : "";
+      prompt = `Add comments to passages in this text following these instructions:
+
+${instructions}${toneGuidance}${densityGuidance}
+
+Text to analyze:
+---
+${content.substring(0, 8e3)}
+---
+
+Return a JSON array of comments. Each comment must have:
+- "exact": the exact text passage being commented on (quoted verbatim from source)
+- "start": character offset where the passage starts
+- "end": character offset where the passage ends
+- "prefix": up to 32 characters of text immediately before the passage
+- "suffix": up to 32 characters of text immediately after the passage
+- "comment": your comment following the instructions above
+
+Respond with a valid JSON array.
+
+Example:
+[
+  {"exact": "the quarterly review meeting", "start": 142, "end": 169, "prefix": "We need to schedule ", "suffix": " for next month.", "comment": "Who will lead this? Should we invite the external auditors?"}
+]`;
+    } else {
+      const toneGuidance = tone ? `
+
+Tone: Use a ${tone} style in your comments.` : "";
+      const densityGuidance = density ? `
+- Aim for approximately ${density} comments per 2000 words` : `
+- Aim for 3-8 comments per 2000 words (not too sparse or dense)`;
+      prompt = `Identify passages in this text that would benefit from explanatory comments.
+For each passage, provide contextual information, clarification, or background.${toneGuidance}
+
+Guidelines:
+- Select passages that reference technical terms, historical figures, complex concepts, or unclear references
+- Provide comments that ADD VALUE beyond restating the text
+- Focus on explanation, background, or connections to other ideas
+- Avoid obvious or trivial comments
+- Keep comments concise (1-3 sentences typically)${densityGuidance}
+
+Text to analyze:
+---
+${content.substring(0, 8e3)}
+---
+
+Return a JSON array of comments. Each comment should have:
+- "exact": the exact text passage being commented on (quoted verbatim from source)
+- "start": character offset where the passage starts
+- "end": character offset where the passage ends
+- "prefix": up to 32 characters of text immediately before the passage
+- "suffix": up to 32 characters of text immediately after the passage
+- "comment": your explanatory comment (1-3 sentences, provide context/background/clarification)
+
+Respond with a valid JSON array.
+
+Example format:
+[
+  {"exact": "Ouranos", "start": 52, "end": 59, "prefix": "In the beginning, ", "suffix": " ruled the universe", "comment": "Ouranos (also spelled Uranus) is the primordial Greek deity personifying the sky. In Hesiod's Theogony, he is the son and husband of Gaia (Earth) and father of the Titans."}
+]`;
+    }
+    return prompt;
+  }
+  /**
+   * Build a prompt for detecting highlight-worthy passages
+   *
+   * @param content - The text content to analyze (will be truncated to 8000 chars)
+   * @param instructions - Optional user-provided instructions
+   * @param density - Optional target number of highlights per 2000 words
+   * @returns Formatted prompt string
+   */
+  static buildHighlightPrompt(content, instructions, density) {
+    let prompt;
+    if (instructions) {
+      const densityGuidance = density ? `
+
+Aim for approximately ${density} highlights per 2000 words of text.` : "";
+      prompt = `Identify passages in this text to highlight following these instructions:
+
+${instructions}${densityGuidance}
+
+Text to analyze:
+---
+${content.substring(0, 8e3)}
+---
+
+Return a JSON array of highlights. Each highlight must have:
+- "exact": the exact text passage to highlight (quoted verbatim from source)
+- "start": character offset where the passage starts
+- "end": character offset where the passage ends
+- "prefix": up to 32 characters of text immediately before the passage
+- "suffix": up to 32 characters of text immediately after the passage
+
+Respond with a valid JSON array.
+
+Example:
+[
+  {"exact": "revenue grew 45% year-over-year", "start": 142, "end": 174, "prefix": "In Q3 2024, ", "suffix": ", exceeding all forecasts."}
+]`;
+    } else {
+      const densityGuidance = density ? `
+- Aim for approximately ${density} highlights per 2000 words` : `
+- Aim for 3-8 highlights per 2000 words (be selective)`;
+      prompt = `Identify passages in this text that merit highlighting for their importance or salience.
+Focus on content that readers should notice and remember.
+
+Guidelines:
+- Highlight key claims, findings, or conclusions
+- Highlight important definitions, terminology, or concepts
+- Highlight notable quotes or particularly striking statements
+- Highlight critical decisions, action items, or turning points
+- Select passages that are SIGNIFICANT, not just interesting
+- Avoid trivial or obvious content${densityGuidance}
+
+Text to analyze:
+---
+${content.substring(0, 8e3)}
+---
+
+Return a JSON array of highlights. Each highlight should have:
+- "exact": the exact text passage to highlight (quoted verbatim from source)
+- "start": character offset where the passage starts
+- "end": character offset where the passage ends
+- "prefix": up to 32 characters of text immediately before the passage
+- "suffix": up to 32 characters of text immediately after the passage
+
+Respond with a valid JSON array.
+
+Example format:
+[
+  {"exact": "we will discontinue support for legacy systems by March 2025", "start": 52, "end": 113, "prefix": "After careful consideration, ", "suffix": ". This decision affects"}
+]`;
+    }
+    return prompt;
+  }
+  /**
+   * Build a prompt for detecting assessment-worthy passages
+   *
+   * @param content - The text content to analyze (will be truncated to 8000 chars)
+   * @param instructions - Optional user-provided instructions
+   * @param tone - Optional tone guidance (e.g., "critical", "supportive")
+   * @param density - Optional target number of assessments per 2000 words
+   * @returns Formatted prompt string
+   */
+  static buildAssessmentPrompt(content, instructions, tone, density) {
+    let prompt;
+    if (instructions) {
+      const toneGuidance = tone ? ` Use a ${tone} tone.` : "";
+      const densityGuidance = density ? `
+
+Aim for approximately ${density} assessments per 2000 words of text.` : "";
+      prompt = `Assess passages in this text following these instructions:
+
+${instructions}${toneGuidance}${densityGuidance}
+
+Text to analyze:
+---
+${content.substring(0, 8e3)}
+---
+
+Return a JSON array of assessments. Each assessment must have:
+- "exact": the exact text passage being assessed (quoted verbatim from source)
+- "start": character offset where the passage starts
+- "end": character offset where the passage ends
+- "prefix": up to 32 characters of text immediately before the passage
+- "suffix": up to 32 characters of text immediately after the passage
+- "assessment": your assessment following the instructions above
+
+Respond with a valid JSON array.
+
+Example:
+[
+  {"exact": "the quarterly revenue target", "start": 142, "end": 169, "prefix": "We established ", "suffix": " for Q4 2024.", "assessment": "This target seems ambitious given market conditions. Consider revising based on recent trends."}
+]`;
+    } else {
+      const toneGuidance = tone ? `
+
+Tone: Use a ${tone} style in your assessments.` : "";
+      const densityGuidance = density ? `
+- Aim for approximately ${density} assessments per 2000 words` : `
+- Aim for 2-6 assessments per 2000 words (focus on key passages)`;
+      prompt = `Identify passages in this text that merit critical assessment or evaluation.
+For each passage, provide analysis of its validity, strength, or implications.${toneGuidance}
+
+Guidelines:
+- Select passages containing claims, arguments, conclusions, or assertions
+- Assess evidence quality, logical soundness, or practical implications
+- Provide assessments that ADD INSIGHT beyond restating the text
+- Focus on passages where evaluation would help readers form judgments
+- Keep assessments concise yet substantive (1-3 sentences typically)${densityGuidance}
+
+Text to analyze:
+---
+${content.substring(0, 8e3)}
+---
+
+Return a JSON array of assessments. Each assessment should have:
+- "exact": the exact text passage being assessed (quoted verbatim from source)
+- "start": character offset where the passage starts
+- "end": character offset where the passage ends
+- "prefix": up to 32 characters of text immediately before the passage
+- "suffix": up to 32 characters of text immediately after the passage
+- "assessment": your analytical assessment (1-3 sentences, evaluate validity/strength/implications)
+
+Respond with a valid JSON array.
+
+Example format:
+[
+  {"exact": "AI will replace most jobs by 2030", "start": 52, "end": 89, "prefix": "Many experts predict that ", "suffix": ", fundamentally reshaping", "assessment": "This claim lacks nuance and supporting evidence. Employment patterns historically show job transformation rather than wholesale replacement. The timeline appears speculative without specific sector analysis."}
+]`;
+    }
+    return prompt;
+  }
+  /**
+   * Build a prompt for detecting structural tags
+   *
+   * @param content - The full text content to analyze (NOT truncated for structural analysis)
+   * @param category - The specific category to detect
+   * @param schemaName - Human-readable schema name
+   * @param schemaDescription - Schema description
+   * @param schemaDomain - Schema domain
+   * @param categoryDescription - Category description
+   * @param categoryExamples - Example questions/guidance for this category
+   * @returns Formatted prompt string
+   */
+  static buildTagPrompt(content, category, schemaName, schemaDescription, schemaDomain, categoryDescription, categoryExamples) {
+    const prompt = `You are analyzing a text using the ${schemaName} framework.
+
+Schema: ${schemaDescription}
+Domain: ${schemaDomain}
+
+Your task: Identify passages that serve the structural role of "${category}".
+
+Category: ${category}
+Description: ${categoryDescription}
+Key questions:
+${categoryExamples.map((ex) => `- ${ex}`).join("\n")}
+
+Guidelines:
+- Focus on STRUCTURAL FUNCTION, not semantic content
+- A passage serves the "${category}" role if it performs this function in the document's structure
+- Look for passages that explicitly fulfill this role
+- Passages can be sentences, paragraphs, or sections
+- Aim for precision - only tag passages that clearly serve this structural role
+- Typical documents have 1-5 instances of each category (some may have 0)
+
+Text to analyze:
+---
+${content}
+---
+
+Return a JSON array of tags. Each tag should have:
+- "exact": the exact text passage (quoted verbatim from source)
+- "start": character offset where the passage starts
+- "end": character offset where the passage ends
+- "prefix": up to 32 characters of text immediately before the passage
+- "suffix": up to 32 characters of text immediately after the passage
+
+Respond with a valid JSON array.
+
+Example format:
+[
+  {"exact": "What duty did the defendant owe?", "start": 142, "end": 175, "prefix": "The central question is: ", "suffix": " This question must be"},
+  {"exact": "In tort law, a duty of care is established when...", "start": 412, "end": 520, "prefix": "Legal framework:\\n", "suffix": "\\n\\nApplying this standard"}
+]`;
+    return prompt;
+  }
+};
+function extractObjectsFromArray(response) {
+  let cleaned = response.trim();
+  if (cleaned.startsWith("```")) {
+    cleaned = cleaned.replace(/^```(?:json)?\s*\n?/, "").replace(/\n?```\s*$/, "");
+  }
+  try {
+    const parsed = JSON.parse(cleaned);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+  }
+  const start = cleaned.indexOf("[");
+  if (start === -1) return [];
+  const endBracket = cleaned.lastIndexOf("]");
+  const end = endBracket > start ? endBracket : cleaned.length;
+  const inner = cleaned.slice(start + 1, end);
+  const objects = [];
+  let depth = 0;
+  let objStart = -1;
+  let inString = false;
+  let escape = false;
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (escape) {
+      escape = false;
+      continue;
+    }
+    if (ch === "\\") {
+      escape = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (ch === "{") {
+      if (depth === 0) objStart = i;
+      depth++;
+    } else if (ch === "}") {
+      depth--;
+      if (depth === 0 && objStart !== -1) {
+        try {
+          objects.push(JSON.parse(inner.slice(objStart, i + 1)));
+        } catch {
+        }
+        objStart = -1;
+      }
+    }
+  }
+  return objects;
+}
+var MotivationParsers = class {
+  /**
+   * Parse and validate AI response for comment detection
+   *
+   * @param response - Raw AI response string (may include markdown code fences)
+   * @param content - Original content to validate offsets against
+   * @returns Array of validated comment matches
+   */
+  static parseComments(response, content) {
+    try {
+      const parsed = extractObjectsFromArray(response);
+      const valid = parsed.filter(
+        (c) => !!c && typeof c === "object" && typeof c.exact === "string" && typeof c.start === "number" && typeof c.end === "number" && typeof c.comment === "string" && c.comment.trim().length > 0
+      );
+      console.log(`[MotivationParsers] Parsed ${valid.length} valid comments from ${parsed.length} total`);
+      const validatedComments = [];
+      for (const comment of valid) {
+        try {
+          const validated = validateAndCorrectOffsets(content, comment.start, comment.end, comment.exact);
+          validatedComments.push({
+            ...comment,
+            start: validated.start,
+            end: validated.end,
+            prefix: validated.prefix,
+            suffix: validated.suffix
+          });
+        } catch (error) {
+          console.warn(`[MotivationParsers] Skipping invalid comment "${comment.exact}":`, error);
+        }
+      }
+      return validatedComments;
+    } catch (error) {
+      console.error("[MotivationParsers] Failed to parse AI comment response:", error);
+      return [];
+    }
+  }
+  /**
+   * Parse and validate AI response for highlight detection
+   *
+   * @param response - Raw AI response string (may include markdown code fences)
+   * @param content - Original content to validate offsets against
+   * @returns Array of validated highlight matches
+   */
+  static parseHighlights(response, content) {
+    try {
+      const parsed = extractObjectsFromArray(response);
+      const highlights = parsed.filter(
+        (h) => !!h && typeof h === "object" && typeof h.exact === "string" && typeof h.start === "number" && typeof h.end === "number"
+      );
+      const validatedHighlights = [];
+      for (const highlight of highlights) {
+        try {
+          const validated = validateAndCorrectOffsets(content, highlight.start, highlight.end, highlight.exact);
+          validatedHighlights.push({
+            ...highlight,
+            start: validated.start,
+            end: validated.end,
+            prefix: validated.prefix,
+            suffix: validated.suffix
+          });
+        } catch (error) {
+          console.warn(`[MotivationParsers] Skipping invalid highlight "${highlight.exact}":`, error);
+        }
+      }
+      return validatedHighlights;
+    } catch (error) {
+      console.error("[MotivationParsers] Failed to parse AI highlight response:", error);
+      console.error("Raw response:", response);
+      return [];
+    }
+  }
+  /**
+   * Parse and validate AI response for assessment detection
+   *
+   * @param response - Raw AI response string (may include markdown code fences)
+   * @param content - Original content to validate offsets against
+   * @returns Array of validated assessment matches
+   */
+  static parseAssessments(response, content) {
+    try {
+      const parsed = extractObjectsFromArray(response);
+      const assessments = parsed.filter(
+        (a) => !!a && typeof a === "object" && typeof a.exact === "string" && typeof a.start === "number" && typeof a.end === "number" && typeof a.assessment === "string"
+      );
+      const validatedAssessments = [];
+      for (const assessment of assessments) {
+        try {
+          const validated = validateAndCorrectOffsets(content, assessment.start, assessment.end, assessment.exact);
+          validatedAssessments.push({
+            ...assessment,
+            start: validated.start,
+            end: validated.end,
+            prefix: validated.prefix,
+            suffix: validated.suffix
+          });
+        } catch (error) {
+          console.warn(`[MotivationParsers] Skipping invalid assessment "${assessment.exact}":`, error);
+        }
+      }
+      return validatedAssessments;
+    } catch (error) {
+      console.error("[MotivationParsers] Failed to parse AI assessment response:", error);
+      console.error("Raw response:", response);
+      return [];
+    }
+  }
+  /**
+   * Parse and validate AI response for tag detection
+   * Note: Does NOT validate offsets - caller must do that with content
+   *
+   * @param response - Raw AI response string (may include markdown code fences)
+   * @returns Array of tag matches (offsets not yet validated)
+   */
+  static parseTags(response) {
+    try {
+      const parsed = extractObjectsFromArray(response);
+      const valid = parsed.filter(
+        (t) => !!t && typeof t === "object" && typeof t.exact === "string" && typeof t.start === "number" && typeof t.end === "number" && t.exact.trim().length > 0
+      );
+      console.log(`[MotivationParsers] Parsed ${valid.length} valid tags from ${parsed.length} total`);
+      return valid;
+    } catch (error) {
+      console.error("[MotivationParsers] Failed to parse AI tag response:", error);
+      return [];
+    }
+  }
+  /**
+   * Validate tag offsets against content and add category
+   * Helper for tag detection after initial parsing
+   *
+   * @param tags - Parsed tags without validated offsets
+   * @param content - Original content to validate against
+   * @param category - Category to assign to validated tags
+   * @returns Array of validated tag matches
+   */
+  static validateTagOffsets(tags, content, category) {
+    const validatedTags = [];
+    for (const tag of tags) {
+      try {
+        const validated = validateAndCorrectOffsets(content, tag.start, tag.end, tag.exact);
+        validatedTags.push({
+          ...tag,
+          category,
+          start: validated.start,
+          end: validated.end,
+          prefix: validated.prefix,
+          suffix: validated.suffix
+        });
+      } catch (error) {
+        console.warn(`[MotivationParsers] Skipping invalid tag for category "${category}":`, error);
+      }
+    }
+    return validatedTags;
+  }
+};
+
+// ../ontology/dist/index.js
+var TAG_SCHEMAS = {
+  "legal-irac": {
+    id: "legal-irac",
+    name: "Legal Analysis (IRAC)",
+    description: "Issue, Rule, Application, Conclusion framework for legal reasoning",
+    domain: "legal",
+    tags: [
+      {
+        name: "Issue",
+        description: "The legal question or problem to be resolved",
+        examples: [
+          "What is the central legal question?",
+          "What must the court decide?",
+          "What is the dispute about?"
+        ]
+      },
+      {
+        name: "Rule",
+        description: "The relevant law, statute, or legal principle",
+        examples: [
+          "What law applies?",
+          "What is the legal standard?",
+          "What statute governs this case?"
+        ]
+      },
+      {
+        name: "Application",
+        description: "How the rule applies to the specific facts",
+        examples: [
+          "How does the law apply to these facts?",
+          "Analysis of the case",
+          "How do the facts satisfy the legal standard?"
+        ]
+      },
+      {
+        name: "Conclusion",
+        description: "The resolution or outcome based on the analysis",
+        examples: [
+          "What is the court's decision?",
+          "What is the final judgment?",
+          "What is the holding?"
+        ]
+      }
+    ]
+  },
+  "scientific-imrad": {
+    id: "scientific-imrad",
+    name: "Scientific Paper (IMRAD)",
+    description: "Introduction, Methods, Results, Discussion structure for research papers",
+    domain: "scientific",
+    tags: [
+      {
+        name: "Introduction",
+        description: "Background, context, and research question",
+        examples: [
+          "What is the research question?",
+          "Why is this important?",
+          "What is the hypothesis?"
+        ]
+      },
+      {
+        name: "Methods",
+        description: "Experimental design and procedures",
+        examples: [
+          "How was the study conducted?",
+          "What methods were used?",
+          "What was the experimental design?"
+        ]
+      },
+      {
+        name: "Results",
+        description: "Findings and observations",
+        examples: [
+          "What did the study find?",
+          "What are the data?",
+          "What were the observations?"
+        ]
+      },
+      {
+        name: "Discussion",
+        description: "Interpretation and implications of results",
+        examples: [
+          "What do the results mean?",
+          "What are the implications?",
+          "How do these findings relate to prior work?"
+        ]
+      }
+    ]
+  },
+  "argument-toulmin": {
+    id: "argument-toulmin",
+    name: "Argument Structure (Toulmin)",
+    description: "Claim, Evidence, Warrant, Counterargument, Rebuttal framework for argumentation",
+    domain: "general",
+    tags: [
+      {
+        name: "Claim",
+        description: "The main assertion or thesis",
+        examples: [
+          "What is being argued?",
+          "What is the main point?",
+          "What position is being taken?"
+        ]
+      },
+      {
+        name: "Evidence",
+        description: "Data or facts supporting the claim",
+        examples: [
+          "What supports this claim?",
+          "What are the facts?",
+          "What data is provided?"
+        ]
+      },
+      {
+        name: "Warrant",
+        description: "Reasoning connecting evidence to claim",
+        examples: [
+          "Why does this evidence support the claim?",
+          "What is the logic?",
+          "How does this reasoning work?"
+        ]
+      },
+      {
+        name: "Counterargument",
+        description: "Opposing viewpoints or objections",
+        examples: [
+          "What are the objections?",
+          "What do critics say?",
+          "What are alternative views?"
+        ]
+      },
+      {
+        name: "Rebuttal",
+        description: "Response to counterarguments",
+        examples: [
+          "How is the objection addressed?",
+          "Why is the counterargument wrong?",
+          "How is the criticism answered?"
+        ]
+      }
+    ]
+  }
+};
+function getTagSchema(schemaId) {
+  return TAG_SCHEMAS[schemaId] || null;
+}
+function getSchemaCategory(schemaId, categoryName) {
+  const schema = getTagSchema(schemaId);
+  if (!schema) return null;
+  return schema.tags.find((tag) => tag.name === categoryName) || null;
+}
+
+// src/workers/annotation-detection.ts
+var AnnotationDetection = class {
+  /**
+   * Fetch content from a ContentFetcher and read the stream to a string.
+   * Shared helper for all workers.
+   */
+  static async fetchContent(contentFetcher, resourceId) {
+    const stream = await contentFetcher(resourceId);
+    if (!stream) {
+      throw new Error(`Could not load content for resource ${resourceId}`);
+    }
+    const chunks = [];
+    for await (const chunk of stream) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+  }
+  /**
+   * Detect comments in content
+   */
+  static async detectComments(content, client, instructions, tone, density) {
+    const prompt = MotivationPrompts.buildCommentPrompt(content, instructions, tone, density);
+    const response = await client.generateText(prompt, 3e3, 0.4);
+    return MotivationParsers.parseComments(response, content);
+  }
+  /**
+   * Detect highlights in content
+   */
+  static async detectHighlights(content, client, instructions, density) {
+    const prompt = MotivationPrompts.buildHighlightPrompt(content, instructions, density);
+    const response = await client.generateText(prompt, 2e3, 0.3);
+    return MotivationParsers.parseHighlights(response, content);
+  }
+  /**
+   * Detect assessments in content
+   */
+  static async detectAssessments(content, client, instructions, tone, density) {
+    const prompt = MotivationPrompts.buildAssessmentPrompt(content, instructions, tone, density);
+    const response = await client.generateText(prompt, 3e3, 0.3);
+    return MotivationParsers.parseAssessments(response, content);
+  }
+  /**
+   * Detect tags in content for a specific category
+   */
+  static async detectTags(content, client, schemaId, category) {
+    const schema = getTagSchema(schemaId);
+    if (!schema) {
+      throw new Error(`Invalid tag schema: ${schemaId}`);
+    }
+    const categoryInfo = getSchemaCategory(schemaId, category);
+    if (!categoryInfo) {
+      throw new Error(`Invalid category "${category}" for schema ${schemaId}`);
+    }
+    const prompt = MotivationPrompts.buildTagPrompt(
+      content,
+      category,
+      schema.name,
+      schema.description,
+      schema.domain,
+      categoryInfo.description,
+      categoryInfo.examples
+    );
+    const response = await client.generateText(prompt, 4e3, 0.2);
+    const parsedTags = MotivationParsers.parseTags(response);
+    return MotivationParsers.validateTagOffsets(parsedTags, content, category);
+  }
+};
+
+// src/workers/detection/entity-extractor.ts
+async function extractEntities(exact, entityTypes, client, includeDescriptiveReferences = false, logger2) {
+  const entityTypesDescription = entityTypes.map((et) => {
+    if (typeof et === "string") {
+      return et;
+    }
+    return et.examples && et.examples.length > 0 ? `${et.type} (examples: ${et.examples.slice(0, 3).join(", ")})` : et.type;
+  }).join(", ");
+  const descriptiveReferenceGuidance = includeDescriptiveReferences ? `
+Include both:
+- Direct mentions (names, proper nouns)
+- Descriptive references (substantive phrases that refer to entities)
+
+For descriptive references, include:
+- Definite descriptions: "the Nobel laureate", "the tech giant", "the former president"
+- Role-based references: "the CEO", "the physicist", "the author", "the owner", "the contractor"
+- Epithets with context: "the Cupertino-based company", "the iPhone maker"
+- References to entities even when identity is unknown or unspecified
+
+Do NOT include:
+- Simple pronouns alone: he, she, it, they, him, her, them
+- Generic determiners alone: this, that, these, those
+- Possessives without substance: his, her, their, its
+
+Examples:
+- For "Marie Curie", include "the Nobel laureate" and "the physicist" but NOT "she"
+- For an unknown person, include "the owner" or "the contractor" (role-based references count even when identity is unspecified)
+` : `
+Find direct mentions only (names, proper nouns). Do not include pronouns or descriptive references.
+`;
+  const prompt = `Identify entity references in the following text. Look for mentions of: ${entityTypesDescription}.
+${descriptiveReferenceGuidance}
+Text to analyze:
+"""
+${exact}
+"""
+
+Respond with a JSON array of entities found. Each entity should have:
+- exact: the exact text span from the input
+- entityType: one of the provided entity types
+- startOffset: character position where the entity starts (0-indexed)
+- endOffset: character position where the entity ends
+- prefix: up to 32 characters of text immediately before the entity (helps identify correct occurrence)
+- suffix: up to 32 characters of text immediately after the entity (helps identify correct occurrence)
+
+If no entities are found, respond with an empty array [].
+
+Example output:
+[{"exact":"Alice","entityType":"Person","startOffset":0,"endOffset":5,"prefix":"","suffix":" went to"},{"exact":"Paris","entityType":"Location","startOffset":20,"endOffset":25,"prefix":"went to ","suffix":" yesterday"}]`;
+  const response = await client.generateTextWithMetadata(
+    prompt,
+    4e3,
+    // Increased to handle many entities without truncation
+    0.3
+    // Lower temperature for more consistent extraction
+  );
+  try {
+    let jsonStr = response.text.trim();
+    if (jsonStr.startsWith("```")) {
+      jsonStr = jsonStr.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "");
+    }
+    const entities = JSON.parse(jsonStr);
+    logger2?.debug("Parsed entities from AI response", { count: entities.length });
+    if (response.stopReason === "max_tokens") {
+      const errorMsg = `AI response truncated: Found ${entities.length} entities but response hit max_tokens limit. Increase max_tokens or reduce resource size.`;
+      logger2?.error(errorMsg);
+      throw new Error(errorMsg);
+    }
+    return entities.map((entity, idx) => {
+      let startOffset = entity.startOffset;
+      let endOffset = entity.endOffset;
+      logger2?.debug("Processing entity", {
+        index: idx + 1,
+        total: entities.length,
+        type: entity.entityType,
+        text: entity.exact,
+        offsetsFromAI: `[${startOffset}:${endOffset}]`
+      });
+      const extractedText = exact.substring(startOffset, endOffset);
+      let anchorMethod;
+      if (extractedText === entity.exact) {
+        anchorMethod = "llm-exact";
+        logger2?.debug("Entity anchored", {
+          text: entity.exact,
+          entityType: entity.entityType,
+          anchorMethod
+        });
+      } else {
+        logger2?.debug("LLM offsets mismatch \u2014 attempting re-anchor", {
+          expected: entity.exact,
+          llmOffsets: `[${startOffset}:${endOffset}]`,
+          foundAtLlmOffsets: extractedText
+        });
+        let occurrenceCount = 0;
+        let firstOccurrence = -1;
+        let searchPos = 0;
+        while ((searchPos = exact.indexOf(entity.exact, searchPos)) !== -1) {
+          if (firstOccurrence === -1) firstOccurrence = searchPos;
+          occurrenceCount++;
+          searchPos++;
+        }
+        if (occurrenceCount === 0) {
+          anchorMethod = "dropped";
+          logger2?.error("Entity text not found in resource \u2014 dropping", {
+            text: entity.exact,
+            entityType: entity.entityType,
+            llmOffsets: `[${startOffset}:${endOffset}]`,
+            anchorMethod,
+            resourceStart: exact.substring(0, 200)
+          });
+          return null;
+        }
+        let recoveredOffset = -1;
+        if (entity.prefix || entity.suffix) {
+          let p = 0;
+          while ((p = exact.indexOf(entity.exact, p)) !== -1) {
+            const candidatePrefix = exact.substring(Math.max(0, p - 32), p);
+            const candidateSuffix = exact.substring(
+              p + entity.exact.length,
+              Math.min(exact.length, p + entity.exact.length + 32)
+            );
+            const prefixMatch = !entity.prefix || candidatePrefix.endsWith(entity.prefix);
+            const suffixMatch = !entity.suffix || candidateSuffix.startsWith(entity.suffix);
+            if (prefixMatch && suffixMatch) {
+              recoveredOffset = p;
+              break;
+            }
+            p++;
+          }
+        }
+        if (recoveredOffset !== -1) {
+          anchorMethod = "context-recovered";
+          startOffset = recoveredOffset;
+          endOffset = recoveredOffset + entity.exact.length;
+          logger2?.debug("Entity anchored", {
+            text: entity.exact,
+            entityType: entity.entityType,
+            anchorMethod,
+            offsetDiff: recoveredOffset - entity.startOffset
+          });
+        } else if (occurrenceCount === 1) {
+          anchorMethod = "unique-match";
+          startOffset = firstOccurrence;
+          endOffset = firstOccurrence + entity.exact.length;
+          logger2?.debug("Entity anchored", {
+            text: entity.exact,
+            entityType: entity.entityType,
+            anchorMethod,
+            offsetDiff: firstOccurrence - entity.startOffset
+          });
+        } else {
+          anchorMethod = "first-of-many";
+          startOffset = firstOccurrence;
+          endOffset = firstOccurrence + entity.exact.length;
+          logger2?.warn("Entity anchored at first of multiple occurrences \u2014 may be wrong", {
+            text: entity.exact,
+            entityType: entity.entityType,
+            anchorMethod,
+            occurrenceCount,
+            chosenOffset: firstOccurrence,
+            llmOffsets: `[${entity.startOffset}:${entity.endOffset}]`,
+            hasPrefix: !!entity.prefix,
+            hasSuffix: !!entity.suffix
+          });
+        }
+      }
+      return {
+        exact: entity.exact,
+        entityType: entity.entityType,
+        startOffset,
+        endOffset,
+        prefix: entity.prefix,
+        suffix: entity.suffix
+      };
+    }).filter((entity) => {
+      if (entity === null) {
+        logger2?.debug("Filtered entity: null");
+        return false;
+      }
+      if (entity.startOffset === void 0 || entity.endOffset === void 0) {
+        logger2?.warn("Filtered entity: missing offsets", { text: entity.exact });
+        return false;
+      }
+      if (entity.startOffset < 0) {
+        logger2?.warn("Filtered entity: negative startOffset", {
+          text: entity.exact,
+          startOffset: entity.startOffset
+        });
+        return false;
+      }
+      if (entity.endOffset > exact.length) {
+        logger2?.warn("Filtered entity: endOffset exceeds text length", {
+          text: entity.exact,
+          endOffset: entity.endOffset,
+          textLength: exact.length
+        });
+        return false;
+      }
+      const extractedText = exact.substring(entity.startOffset, entity.endOffset);
+      if (extractedText !== entity.exact) {
+        logger2?.warn("Filtered entity: offset mismatch", {
+          expected: entity.exact,
+          got: extractedText,
+          offsets: `[${entity.startOffset}:${entity.endOffset}]`
+        });
+        return false;
+      }
+      logger2?.debug("Accepted entity", {
+        text: entity.exact,
+        offsets: `[${entity.startOffset}:${entity.endOffset}]`
+      });
+      return true;
+    });
+  } catch (error) {
+    return [];
+  }
+}
+function getLanguageName(locale) {
+  return getLocaleEnglishName(locale) || locale;
+}
+async function generateResourceFromTopic(topic, entityTypes, client, userPrompt, locale, context, temperature, maxTokens, logger2) {
+  const finalTemperature = temperature ?? 0.7;
+  const finalMaxTokens = maxTokens ?? 500;
+  const languageInstruction = locale && locale !== "en" ? `
+
+IMPORTANT: Write the entire resource in ${getLanguageName(locale)}.` : "";
+  let annotationSection = "";
+  if (context) {
+    const parts = [];
+    parts.push(`- Annotation motivation: ${context.annotation.motivation}`);
+    parts.push(`- Source resource: ${context.sourceResource.name}`);
+    const { motivation, body } = context.annotation;
+    if (motivation === "commenting" || motivation === "assessing") {
+      const bodyItem = Array.isArray(body) ? body[0] : body;
+      if (bodyItem && "value" in bodyItem && bodyItem.value) {
+        const label = motivation === "commenting" ? "Comment" : "Assessment";
+        parts.push(`- ${label}: ${bodyItem.value}`);
+      }
+    }
+    annotationSection = `
+
+Annotation context:
+${parts.join("\n")}`;
+  }
+  let contextSection = "";
+  if (context?.sourceContext) {
+    const { before, selected, after } = context.sourceContext;
+    contextSection = `
+
+Source document context:
+---
+${before ? `...${before}` : ""}
+**[${selected}]**
+${after ? `${after}...` : ""}
+---
+`;
+  }
+  let graphContextSection = "";
+  if (context?.graphContext) {
+    const gc = context.graphContext;
+    const connections = gc.connections ?? [];
+    const citedBy = gc.citedBy ?? [];
+    const parts = [];
+    if (connections.length > 0) {
+      const connList = connections.map((c) => `${c.resourceName}${c.entityTypes?.length ? ` (${c.entityTypes.join(", ")})` : ""}`).join(", ");
+      parts.push(`- Connected resources: ${connList}`);
+    }
+    if (gc.citedByCount && gc.citedByCount > 0) {
+      const citedNames = citedBy.map((c) => c.resourceName).join(", ");
+      parts.push(`- This resource is cited by ${gc.citedByCount} other resource${gc.citedByCount > 1 ? "s" : ""}${citedNames ? `: ${citedNames}` : ""}`);
+    }
+    if (gc.siblingEntityTypes && gc.siblingEntityTypes.length > 0) {
+      parts.push(`- Related entity types in this document: ${gc.siblingEntityTypes.join(", ")}`);
+    }
+    if (gc.inferredRelationshipSummary) {
+      parts.push(`- Relationship summary: ${gc.inferredRelationshipSummary}`);
+    }
+    if (parts.length > 0) {
+      graphContextSection = `
+
+Knowledge graph context:
+${parts.join("\n")}`;
+    }
+  }
+  const structureGuidance = finalMaxTokens >= 1e3 ? "organized into titled sections (## Section) with well-structured paragraphs" : "organized into well-structured paragraphs";
+  const prompt = `Generate a concise, informative resource about "${topic}".
+${entityTypes.length > 0 ? `Focus on these entity types: ${entityTypes.join(", ")}.` : ""}
+${userPrompt ? `Additional context: ${userPrompt}` : ""}${annotationSection}${contextSection}${graphContextSection}${languageInstruction}
+
+Requirements:
+- Start with a clear heading (# Title)
+- Aim for approximately ${finalMaxTokens} tokens of content, ${structureGuidance}
+- Be factual and informative
+- Use markdown formatting
+- Write the response as markdown`;
+  const parseResponse = (response2) => {
+    let content = response2.trim();
+    if (content.startsWith("```markdown") || content.startsWith("```md")) {
+      content = content.slice(content.indexOf("\n") + 1);
+      const endIndex = content.lastIndexOf("```");
+      if (endIndex !== -1) {
+        content = content.slice(0, endIndex);
+      }
+    } else if (content.startsWith("```")) {
+      content = content.slice(3);
+      const endIndex = content.lastIndexOf("```");
+      if (endIndex !== -1) {
+        content = content.slice(0, endIndex);
+      }
+    }
+    content = content.trim();
+    return {
+      title: topic,
+      content
+    };
+  };
+  const response = await client.generateText(prompt, finalMaxTokens, finalTemperature);
+  const result = parseResponse(response);
+  return result;
+}
+function buildTextAnnotation(resourceId, userId, generator, motivation, match, body) {
+  return {
+    "@context": "http://www.w3.org/ns/anno.jsonld",
+    "type": "Annotation",
+    "id": generateAnnotationId(),
+    motivation,
+    creator: didToAgent(userId),
+    generator,
+    created: (/* @__PURE__ */ new Date()).toISOString(),
+    target: {
+      type: "SpecificResource",
+      source: resourceId,
+      selector: [
+        { type: "TextPositionSelector", start: match.start, end: match.end },
+        {
+          type: "TextQuoteSelector",
+          exact: match.exact,
+          ...match.prefix && { prefix: match.prefix },
+          ...match.suffix && { suffix: match.suffix }
+        }
+      ]
+    },
+    ...body !== void 0 ? { body } : {}
+  };
+}
+async function processHighlightJob(content, inferenceClient, params, userId, generator, onProgress) {
+  onProgress(10, "Loading resource...", "analyzing");
+  onProgress(30, "Analyzing text...", "analyzing");
+  const highlights = await AnnotationDetection.detectHighlights(
+    content,
+    inferenceClient,
+    params.instructions,
+    params.density
+  );
+  onProgress(60, `Creating ${highlights.length} annotations...`, "creating");
+  const annotations = highlights.map(
+    (h) => buildTextAnnotation(params.resourceId, userId, generator, "highlighting", h)
+  );
+  onProgress(100, `Complete! Created ${annotations.length} highlights`, "creating");
+  return {
+    annotations,
+    result: { highlightsFound: highlights.length, highlightsCreated: annotations.length }
+  };
+}
+async function processCommentJob(content, inferenceClient, params, userId, generator, onProgress) {
+  onProgress(10, "Loading resource...", "analyzing");
+  onProgress(30, "Analyzing text...", "analyzing");
+  const comments = await AnnotationDetection.detectComments(
+    content,
+    inferenceClient,
+    params.instructions,
+    params.tone,
+    params.density
+  );
+  onProgress(60, `Creating ${comments.length} annotations...`, "creating");
+  const annotations = comments.map(
+    (c) => (
+      // Match the pre-#651 CommentAnnotationWorker: include format and
+      // language on the body TextualBody. Optional in the schema, but
+      // consumers that do language-aware rendering rely on them.
+      buildTextAnnotation(params.resourceId, userId, generator, "commenting", c, [
+        { type: "TextualBody", value: c.comment, purpose: "commenting", format: "text/plain", language: "en" }
+      ])
+    )
+  );
+  onProgress(100, `Complete! Created ${annotations.length} comments`, "creating");
+  return {
+    annotations,
+    result: { commentsFound: comments.length, commentsCreated: annotations.length }
+  };
+}
+async function processAssessmentJob(content, inferenceClient, params, userId, generator, onProgress) {
+  onProgress(10, "Loading resource...", "analyzing");
+  onProgress(30, "Analyzing text...", "analyzing");
+  const assessments = await AnnotationDetection.detectAssessments(
+    content,
+    inferenceClient,
+    params.instructions,
+    params.tone,
+    params.density
+  );
+  onProgress(60, `Creating ${assessments.length} annotations...`, "creating");
+  const annotations = assessments.map(
+    (a) => (
+      // Single-object body with purpose aligned to motivation, matching the
+      // pre-#651 AssessmentAnnotationWorker's shape and the majority of
+      // persisted assessments. Do not switch to an array or to
+      // purpose='describing' — that loses the "this is an assessment, not
+      // a description" signal and breaks existing readers that access
+      // `body.value` directly on the object.
+      buildTextAnnotation(params.resourceId, userId, generator, "assessing", a, {
+        type: "TextualBody",
+        value: a.assessment,
+        purpose: "assessing",
+        format: "text/plain",
+        language: "en"
+      })
+    )
+  );
+  onProgress(100, `Complete! Created ${annotations.length} assessments`, "creating");
+  return {
+    annotations,
+    result: { assessmentsFound: assessments.length, assessmentsCreated: annotations.length }
+  };
+}
+async function processReferenceJob(content, inferenceClient, params, userId, generator, onProgress, logger2) {
+  const entityTypeNames = params.entityTypes.map(String);
+  const requestParams = [{ label: "Entity types", value: entityTypeNames.join(", ") }];
+  const completedEntityTypes = [];
+  let totalFound = 0;
+  let totalEmitted = 0;
+  let errors = 0;
+  const allAnnotations = [];
+  onProgress(10, "Loading resource...", "analyzing", { requestParams });
+  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,
+      entitiesFound: totalFound,
+      entitiesEmitted: totalEmitted,
+      completedEntityTypes: [...completedEntityTypes],
+      requestParams
+    });
+    const extractedEntities = await extractEntities(
+      content,
+      [entityTypeName],
+      inferenceClient,
+      params.includeDescriptiveReferences ?? false,
+      logger2
+    );
+    totalFound += extractedEntities.length;
+    completedEntityTypes.push({ entityType: entityTypeName, foundCount: extractedEntities.length });
+    const unresolvedBody = [{ type: "TextualBody", value: entityTypeName, purpose: "tagging" }];
+    for (const entity of extractedEntities) {
+      try {
+        const validated = validateAndCorrectOffsets(content, entity.startOffset, entity.endOffset, entity.exact);
+        const ann = buildTextAnnotation(
+          params.resourceId,
+          userId,
+          generator,
+          "linking",
+          validated,
+          unresolvedBody
+        );
+        allAnnotations.push(ann);
+        totalEmitted++;
+      } catch {
+        errors++;
+      }
+    }
+  }
+  onProgress(100, `Complete! Created ${totalEmitted} references`, "creating");
+  return {
+    annotations: allAnnotations,
+    result: { totalFound, totalEmitted, errors }
+  };
+}
+async function processTagJob(content, inferenceClient, params, userId, generator, onProgress) {
+  onProgress(10, "Loading resource...", "analyzing");
+  onProgress(30, "Analyzing text for tags...", "analyzing");
+  const allTags = [];
+  for (const category of params.categories) {
+    const categoryTags = await AnnotationDetection.detectTags(
+      content,
+      inferenceClient,
+      params.schemaId,
+      category
+    );
+    allTags.push(...categoryTags);
+  }
+  const tags = allTags;
+  onProgress(60, `Creating ${tags.length} tag annotations...`, "creating");
+  const byCategory = {};
+  const annotations = tags.map((t) => {
+    const category = t.category ?? "unknown";
+    byCategory[category] = (byCategory[category] ?? 0) + 1;
+    return buildTextAnnotation(params.resourceId, userId, generator, "tagging", t, [
+      { type: "TextualBody", value: category, purpose: "tagging", format: "text/plain", language: "en" },
+      { type: "TextualBody", value: params.schemaId, purpose: "classifying", format: "text/plain" }
+    ]);
+  });
+  onProgress(100, `Complete! Created ${annotations.length} tags`, "creating");
+  return {
+    annotations,
+    result: { tagsFound: tags.length, tagsCreated: annotations.length, byCategory }
+  };
+}
+async function processGenerationJob(inferenceClient, params, onProgress) {
+  onProgress(20, "Fetching context...", "fetching");
+  const title = params.title ?? "Untitled";
+  const entityTypes = (params.entityTypes ?? []).map(String);
+  onProgress(40, "Generating resource...", "generating");
+  const generated = await generateResourceFromTopic(
+    title,
+    entityTypes,
+    inferenceClient,
+    params.prompt,
+    params.language,
+    params.context,
+    params.temperature,
+    params.maxTokens
+  );
+  onProgress(85, "Creating resource...", "creating");
+  return {
+    content: generated.content,
+    title: generated.title ?? title,
+    format: "text/markdown",
+    result: {
+      resourceId: "",
+      resourceName: generated.title ?? title
+    }
+  };
+}
+
+// src/worker-process.ts
+async function emitEvent(session, channel, payload) {
+  const isBroadcast = RESOURCE_BROADCAST_TYPES.includes(channel);
+  const resourceScope = isBroadcast ? payload.resourceId : void 0;
+  await session.client.actor.emit(channel, payload, resourceScope);
+}
+function startWorkerProcess(config) {
+  const { session, logger: logger2 } = config;
+  const adapter = createJobClaimAdapter({
+    actor: session.client.actor,
+    jobTypes: config.jobTypes
+  });
+  adapter.activeJob$.subscribe((job) => {
+    if (!job) return;
+    logger2.info("Processing job", { jobId: job.jobId, type: job.type, resourceId: job.resourceId });
+    handleJob(adapter, config, job).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      logger2.error("Job failed", { jobId: job.jobId, error: message, stack: error instanceof Error ? error.stack : void 0 });
+      const failAnnotationId = job.params.referenceId;
+      emitEvent(session, "job:fail", {
+        resourceId: job.resourceId,
+        userId: job.userId,
+        jobId: job.jobId,
+        jobType: job.type,
+        ...failAnnotationId ? { annotationId: failAnnotationId } : {},
+        error: message
+      }).catch(() => {
+      });
+      adapter.failJob(job.jobId, message);
+    });
+  });
+  adapter.start();
+  return adapter;
+}
+async function handleJob(adapter, config, job) {
+  const { session } = config;
+  const { resourceId, userId, jobId, type: jobType } = job;
+  const annotationId = job.params.referenceId;
+  const lifecycleBase = {
+    resourceId,
+    userId,
+    jobId,
+    jobType,
+    ...annotationId ? { annotationId } : {}
+  };
+  await emitEvent(session, "job:start", lifecycleBase);
+  const engine = config.engines[jobType];
+  if (!engine) {
+    adapter.failJob(jobId, `No inference engine configured for job type: ${jobType}`);
+    return;
+  }
+  const { inferenceClient, generator } = engine;
+  const onProgress = (percentage, message, stage, extra) => {
+    emitEvent(session, "job:report-progress", {
+      ...lifecycleBase,
+      percentage,
+      progress: {
+        stage,
+        percentage,
+        message,
+        ...annotationId ? { annotationId } : {},
+        ...extra ?? {}
+      }
+    }).catch(() => {
+    });
+  };
+  const fetchContent = async () => {
+    return await session.client.browse.resourceContent(resourceId);
+  };
+  if (jobType === "highlight-annotation") {
+    const content = await fetchContent();
+    const { annotations, result } = await processHighlightJob(
+      content,
+      inferenceClient,
+      job.params,
+      userId,
+      generator,
+      onProgress
+    );
+    for (const ann of annotations) {
+      await emitEvent(session, "mark:create", { annotation: ann, userId, resourceId });
+    }
+    await emitEvent(session, "job:complete", {
+      ...lifecycleBase,
+      result
+    });
+    adapter.completeJob();
+  } else if (jobType === "comment-annotation") {
+    const content = await fetchContent();
+    const { annotations, result } = await processCommentJob(
+      content,
+      inferenceClient,
+      job.params,
+      userId,
+      generator,
+      onProgress
+    );
+    for (const ann of annotations) {
+      await emitEvent(session, "mark:create", { annotation: ann, userId, resourceId });
+    }
+    await emitEvent(session, "job:complete", {
+      ...lifecycleBase,
+      result
+    });
+    adapter.completeJob();
+  } else if (jobType === "assessment-annotation") {
+    const content = await fetchContent();
+    const { annotations, result } = await processAssessmentJob(
+      content,
+      inferenceClient,
+      job.params,
+      userId,
+      generator,
+      onProgress
+    );
+    for (const ann of annotations) {
+      await emitEvent(session, "mark:create", { annotation: ann, userId, resourceId });
+    }
+    await emitEvent(session, "job:complete", {
+      ...lifecycleBase,
+      result
+    });
+    adapter.completeJob();
+  } else if (jobType === "reference-annotation") {
+    const content = await fetchContent();
+    const { annotations, result } = await processReferenceJob(
+      content,
+      inferenceClient,
+      job.params,
+      userId,
+      generator,
+      onProgress
+    );
+    for (const ann of annotations) {
+      await emitEvent(session, "mark:create", { annotation: ann, userId, resourceId });
+    }
+    await emitEvent(session, "job:complete", {
+      ...lifecycleBase,
+      result
+    });
+    adapter.completeJob();
+  } else if (jobType === "tag-annotation") {
+    const content = await fetchContent();
+    const { annotations, result } = await processTagJob(
+      content,
+      inferenceClient,
+      job.params,
+      userId,
+      generator,
+      onProgress
+    );
+    for (const ann of annotations) {
+      await emitEvent(session, "mark:create", { annotation: ann, userId, resourceId });
+    }
+    await emitEvent(session, "job:complete", {
+      ...lifecycleBase,
+      result
+    });
+    adapter.completeJob();
+  } else if (jobType === "generation") {
+    const genResult = await processGenerationJob(
+      inferenceClient,
+      job.params,
+      onProgress
+    );
+    const genParams = job.params;
+    const storageUri = deriveStorageUri(genResult.title, genResult.format);
+    const { resourceId: newResourceId } = await session.client.yield.resource({
+      name: genResult.title,
+      file: Buffer.from(genResult.content),
+      format: genResult.format,
+      storageUri,
+      creationMethod: "generated",
+      sourceResourceId: resourceId,
+      ...genParams.referenceId ? { sourceAnnotationId: genParams.referenceId } : {},
+      ...genParams.prompt ? { generationPrompt: genParams.prompt } : {},
+      ...genParams.language ? { language: genParams.language } : {},
+      generator
+    });
+    await emitEvent(session, "job:complete", {
+      ...lifecycleBase,
+      result: { resourceId: newResourceId, resourceName: genResult.title }
+    });
+    adapter.completeJob();
+  } else {
+    adapter.failJob(jobId, `Unknown job type: ${jobType}`);
+  }
+}
+function createProcessLogger(component) {
+  const level = process.env.LOG_LEVEL ?? "info";
+  const format = process.env.LOG_FORMAT === "simple" ? winston.format.combine(
+    winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
+    winston.format.errors({ stack: true }),
+    winston.format.printf(({ level: lvl, message, timestamp, ...meta }) => {
+      const metaStr = Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : "";
+      return `${timestamp} [${lvl.toUpperCase()}] [${component}] ${message}${metaStr}`;
+    })
+  ) : winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.errors({ stack: true }),
+    winston.format.json()
+  );
+  const logger2 = winston.createLogger({
+    level,
+    defaultMeta: { component },
+    format,
+    transports: [new winston.transports.Console()]
+  });
+  return logger2;
+}
+
+// src/worker-main.ts
+var ALL_JOB_TYPES = [
+  "reference-annotation",
+  "generation",
+  "highlight-annotation",
+  "assessment-annotation",
+  "comment-annotation",
+  "tag-annotation"
+];
+var configPath = join(homedir(), ".semiontconfig");
+var tomlReader = {
+  readIfExists: (p) => existsSync(p) ? readFileSync(p, "utf-8") : null
+};
+var envConfig = createTomlConfigLoader(
+  tomlReader,
+  configPath,
+  process.env
+)(null, "local");
+var workerInferenceMap = envConfig._metadata?.workers;
+if (!workerInferenceMap || Object.keys(workerInferenceMap).length === 0) {
+  throw new Error(
+    'No worker inference config found in ~/.semiontconfig. Add at least [environments.<env>.workers.default.inference] with type = "..." and model = "...".'
+  );
+}
+function resolveWorker(jobType) {
+  const specific = workerInferenceMap[jobType];
+  if (specific) return specific;
+  const def = workerInferenceMap["default"];
+  if (def) return def;
+  throw new Error(
+    `No inference config for worker '${jobType}' and no workers.default in ~/.semiontconfig.`
+  );
+}
+var backendPublicURL = envConfig.services?.backend?.publicURL;
+if (!backendPublicURL) {
+  throw new Error("services.backend.publicURL is required in ~/.semiontconfig");
+}
+var backendBaseUrl = backendPublicURL;
+var workerSecret = process.env.SEMIONT_WORKER_SECRET ?? "";
+var healthPort = 9090;
+var logger = createProcessLogger("worker");
+function clientKey(w) {
+  return [w.type, w.model, w.apiKey ?? "", w.endpoint ?? "", w.baseURL ?? ""].join("|");
+}
+function toClientConfig(w) {
+  return {
+    type: w.type,
+    model: w.model,
+    ...w.endpoint && { endpoint: w.endpoint },
+    ...w.baseURL && { baseURL: w.baseURL },
+    ...w.apiKey && { apiKey: w.apiKey }
+  };
+}
+var clientCache = /* @__PURE__ */ new Map();
+var engines = {};
+for (const jobType of ALL_JOB_TYPES) {
+  const w = resolveWorker(jobType);
+  const key = clientKey(w);
+  let client = clientCache.get(key);
+  if (!client) {
+    client = createInferenceClient(toClientConfig(w), logger);
+    clientCache.set(key, client);
+  }
+  const generator = {
+    "@type": "SoftwareAgent",
+    name: `worker-pool / ${w.type} ${w.model}`,
+    worker: "worker-pool",
+    inferenceProvider: w.type,
+    model: w.model
+  };
+  engines[jobType] = { inferenceClient: client, generator };
+}
+function parseBackendUrl(url) {
+  const parsed = new URL(url);
+  const protocol = parsed.protocol.replace(":", "") === "https" ? "https" : "http";
+  const host = parsed.hostname;
+  const port = parsed.port ? Number(parsed.port) : protocol === "https" ? 443 : 80;
+  return { protocol, host, port };
+}
+async function authenticate() {
+  if (!workerSecret) {
+    logger.warn("No SEMIONT_WORKER_SECRET set \u2014 using empty token");
+    return "";
+  }
+  const response = await fetch(`${backendBaseUrl}/api/tokens/worker`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ secret: workerSecret })
+  });
+  if (!response.ok) {
+    throw new Error(`Authentication failed: ${response.status} ${response.statusText}`);
+  }
+  const { token } = await response.json();
+  return token;
+}
+async function main() {
+  logger.info("Authenticating", { baseUrl: backendBaseUrl });
+  const initialToken = await authenticate();
+  logger.info("Authenticated");
+  const { protocol, host, port } = parseBackendUrl(backendBaseUrl);
+  const kbId = `worker-${hostname()}`;
+  const kb = {
+    id: kbId,
+    label: `Worker pool @ ${host}`,
+    host,
+    port,
+    protocol,
+    email: `worker-pool@${host}`
+  };
+  const storage = new InMemorySessionStorage();
+  setStoredSession(storage, kbId, { access: initialToken, refresh: "" });
+  const session = new SemiontSession({
+    kb,
+    storage,
+    refresh: async () => {
+      try {
+        return await authenticate();
+      } catch (err) {
+        logger.error("Worker token refresh failed", {
+          error: err instanceof Error ? err.message : String(err)
+        });
+        return null;
+      }
+    },
+    // No validate callback — workers are service principals with no
+    // user record to fetch. `session.user$` stays null.
+    onError: (err) => {
+      logger.error("Session error", { code: err.code, message: err.message });
+    }
+  });
+  await session.ready;
+  const workerVm = startWorkerProcess({
+    session,
+    jobTypes: ALL_JOB_TYPES,
+    engines,
+    logger
+  });
+  logger.info("Connected", {
+    baseUrl: backendBaseUrl,
+    engines: Object.fromEntries(
+      Object.entries(engines).map(([jt, e]) => [jt, `${e.generator.inferenceProvider} / ${e.generator.model}`])
+    )
+  });
+  const health = createServer((req, res) => {
+    if (req.url === "/health") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "ok" }));
+    } else {
+      res.writeHead(404);
+      res.end();
+    }
+  });
+  health.listen(healthPort, () => {
+    logger.info("Health endpoint ready", { port: healthPort });
+  });
+  const shutdown = async () => {
+    logger.info("Shutting down");
+    workerVm.dispose();
+    await session.dispose();
+    health.close();
+    process.exit(0);
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}
+main().catch((error) => {
+  logger.error("Fatal", { error: error instanceof Error ? error.message : String(error), stack: error instanceof Error ? error.stack : void 0 });
+  process.exit(1);
+});
+//# sourceMappingURL=worker-main.js.map
+//# sourceMappingURL=worker-main.js.map