@vibesdotdev/docs 0.0.0-stage → 1.0.0-rc.3

package/dist/documents/tools/descriptors.js

@@ -0,0 +1,78 @@
+/**
+ * Document agent-tool descriptors.
+ *
+ * Declares the `document.read` tool via `createRuntimeAsset`. The impl
+ * (cache-first orchestration, render delegation, vision-OCR) lives in
+ * `document-read.impl.ts` and is loaded lazily by the plugin.
+ */
+import { createRuntimeAsset } from '@vibesdotdev/kernel/factory';
+import { DocumentReadInputSchema, DocumentReadOutputSchema } from "../schemas/document-read.schema.js";
+import { DocumentViewInputSchema, DocumentViewOutputSchema } from "../schemas/document-view.schema.js";
+export const DOCUMENT_TOOL_IDS = ['document.read', 'document.view'];
+export function isDocumentToolId(value) {
+    return DOCUMENT_TOOL_IDS.some((id) => id === value);
+}
+const common = {
+    kind: 'tools/tool',
+    hardware: ['consumer', 'cloud'],
+    purpose: ['agent', 'direct', 'worker'],
+    category: 'documents',
+    tags: ['documents', 'pdf', 'ocr', 'vision']
+};
+export const documentReadToolDescriptor = createRuntimeAsset({
+    ...common,
+    id: 'document.read',
+    name: 'Read Document',
+    description: 'Read one or more pages from a PDF or document file. Uses cached OCR/vision results when available; otherwise renders the page, runs vision-OCR via the drainer, and writes the result to the page cache. Optionally extracts structured data according to a JSON schema.',
+    // mcpDescription hard-capped at 90 by check-tool-coverage (MCP-safe limit).
+    // Keep the "Every call requires ref" guardrail visible to the model — the
+    // casework takeoff loop regressed when document.read was called with `{}`
+    // (descriptor.test.ts locks this rule into the model-facing string).
+    mcpDescription: 'Read PDF/doc pages. Every call requires ref:{url,...}. Cache-first OCR; optional schema.',
+    subcategory: 'read',
+    safety: 'read',
+    requiresApproval: false,
+    schemas: {
+        input: DocumentReadInputSchema,
+        output: DocumentReadOutputSchema
+    },
+    usageGuidance: {
+        when: 'Use when the user wants to read, extract, or query content from a document file (PDF, etc.).',
+        commonPatterns: [
+            'Every call must include `ref`; never call document.read with `{}`. Reuse the full `ref` object from the source/lookup tool on every page read.',
+            'Read the index/TOC page first (page 1 or pass no pages), then target only the sheets you need.',
+            'Pass vocabulary hints for domain-specific terms (part numbers, trade names) to improve OCR accuracy.',
+            'Pass a JSON schema in the `schema` field to get structured rows instead of raw markdown.',
+            'Pass `question` for a direct answer without full structured extraction.',
+            'Use `visionFocusHint` ("large drawing", "dense text", "table") to guide tiling strategy.',
+            'Bump `promptVersion` to force re-OCR when the document source changes or you update extraction prompts.'
+        ]
+    }
+});
+export const documentViewToolDescriptor = createRuntimeAsset({
+    ...common,
+    id: 'document.view',
+    name: 'View Document Drawing',
+    description: 'Render a drawing/PDF page as an IMAGE for you to look at directly, instead of a transcription. Call with no region to see the whole sheet (downscaled, to orient); call again with region:{x,y,w,h} in 0..1 sheet fractions to zoom into a spot and read dimensions, labels, and keynotes with your own eyes. This is how you read a drawing like an estimator: scan the sheet, then lean in.',
+    // mcpDescription hard-capped at 90 by check-tool-coverage (MCP-safe limit).
+    mcpDescription: 'See a drawing page as an image. ref+page for the whole sheet; add region:{x,y,w,h} to zoom.',
+    subcategory: 'read',
+    safety: 'read',
+    requiresApproval: false,
+    schemas: {
+        input: DocumentViewInputSchema,
+        output: DocumentViewOutputSchema
+    },
+    usageGuidance: {
+        when: 'Use to READ a drawing/technical sheet yourself — to see it and judge what is on it (the elements, dimensions, quantities) from the actual pixels, not a transcription.',
+        commonPatterns: [
+            'Every call needs `ref` (reuse the full ref from the source/lookup tool) and `page`.',
+            'FIRST call with NO region to see the whole sheet and orient — find where the content you need lives on the sheet.',
+            'THEN call again with region:{x,y,w,h} (fractions 0..1 of the sheet, top-left origin) to zoom into that area and read the dimensions and labels.',
+            'Zoom into a SMALLER region (e.g. w:0.3,h:0.3) for finer detail — a tighter crop spends the whole image on less area, so small text becomes legible.',
+            'You are the one reading the drawing: count distinct units, read the dimension chains, and decide what is relevant — do not defer that judgement to a transcription.'
+        ]
+    }
+});
+export const documentToolDescriptors = [documentReadToolDescriptor, documentViewToolDescriptor];
+//# sourceMappingURL=descriptors.js.map

package/dist/documents/tools/descriptors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptors.js","sourceRoot":"","sources":["../../../src/documents/tools/descriptors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AACvG,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAEvG,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,eAAe,EAAE,eAAe,CAAU,CAAC;AAI7E,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC7C,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,KAAK,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,MAAM,GAAG;IACd,IAAI,EAAE,YAAqB;IAC3B,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAU;IACxC,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAU;IAC/C,QAAQ,EAAE,WAAW;IACrB,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;CAC3C,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG,kBAAkB,CAAC;IAC5D,GAAG,MAAM;IACT,EAAE,EAAE,eAAe;IACnB,IAAI,EAAE,eAAe;IACrB,WAAW,EACV,0QAA0Q;IAC3Q,4EAA4E;IAC5E,0EAA0E;IAC1E,0EAA0E;IAC1E,qEAAqE;IACrE,cAAc,EACb,0FAA0F;IAC3F,WAAW,EAAE,MAAM;IACnB,MAAM,EAAE,MAAM;IACd,gBAAgB,EAAE,KAAK;IACvB,OAAO,EAAE;QACR,KAAK,EAAE,uBAAuB;QAC9B,MAAM,EAAE,wBAAwB;KAChC;IACD,aAAa,EAAE;QACd,IAAI,EAAE,8FAA8F;QACpG,cAAc,EAAE;YACf,gJAAgJ;YAChJ,gGAAgG;YAChG,sGAAsG;YACtG,0FAA0F;YAC1F,yEAAyE;YACzE,0FAA0F;YAC1F,yGAAyG;SACzG;KACD;CACD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,0BAA0B,GAAG,kBAAkB,CAAC;IAC5D,GAAG,MAAM;IACT,EAAE,EAAE,eAAe;IACnB,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EACV,+XAA+X;IAChY,4EAA4E;IAC5E,cAAc,EACb,6FAA6F;IAC9F,WAAW,EAAE,MAAM;IACnB,MAAM,EAAE,MAAM;IACd,gBAAgB,EAAE,KAAK;IACvB,OAAO,EAAE;QACR,KAAK,EAAE,uBAAuB;QAC9B,MAAM,EAAE,wBAAwB;KAChC;IACD,aAAa,EAAE;QACd,IAAI,EAAE,wKAAwK;QAC9K,cAAc,EAAE;YACf,qFAAqF;YACrF,mHAAmH;YACnH,iJAAiJ;YACjJ,qJAAqJ;YACrJ,qKAAqK;SACrK;KACD;CACD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,0BAA0B,EAAE,0BAA0B,CAAU,CAAC"}

package/dist/documents/tools/document-read-loop-guard.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `document.read` loop guard — the MECHANISM, not anyone's domain.
+ *
+ * A turn that keeps re-reading queued pages, retrying dead pages, or burning its
+ * budget on sheet after sheet is looping, not progressing. This decides when to
+ * stop and hands back the copy to stop WITH.
+ *
+ * It used to live in the platform chat app under a customer's name
+ * (`casework-document-read-guard.ts`), which put one org's vocabulary and prose
+ * inside a surface every org shares. Everything here is generic; the parts that
+ * ARE domain — which words make a line worth quoting, and the summary sentences —
+ * are injected via {@link DocumentReadEvidenceVocabulary} and default to neutral.
+ * Callers pass plain word LISTS, never regex sources, so a preference travelling
+ * as JSON from an org app can never smuggle in a pattern.
+ */
+type ToolCallLike = {
+    name?: unknown;
+    status?: unknown;
+    output?: unknown;
+    error?: unknown;
+};
+/**
+ * The domain half, supplied by the caller (an org app's declared preference).
+ * Everything is JSON-serializable so it can ride on staged context.
+ */
+export interface DocumentReadEvidenceVocabulary {
+    /**
+     * Words that mark a line as naming a subject worth quoting back as evidence
+     * (e.g. a millwork shop: casework, cabinet, counter). Matched whole-word,
+     * case-insensitive, and ESCAPED — these are words, not patterns.
+     * Omit to fall back to detail-bearing lines alone.
+     */
+    subjectWords?: string[];
+    /** Sentence used when the guard stops and DID find evidence lines. */
+    foundSummary?: string;
+    /** Sentence used when no legible evidence lines were found. */
+    noEvidenceSummary?: string;
+}
+export type DocumentReadLoopGuardDecision = {
+    shouldStop: boolean;
+    reason?: 'document-read-budget' | 'repeated-processing-page' | 'repeated-error-page' | 'document-read-errors' | 'vision-executor-unavailable';
+    fallbackContent?: string;
+    documentReadCount: number;
+    readyPageCount: number;
+    processingPageCount: number;
+    failedReadCount: number;
+};
+export declare function evaluateDocumentReadLoopGuard(toolCalls: Iterable<ToolCallLike>, options?: {
+    currentContent?: string;
+    userMessage?: string;
+    maxEmptyDocumentReads?: number;
+    maxRepeatedProcessingPage?: number;
+    maxRepeatedProcessingPageWithContent?: number;
+    maxDocumentReads?: number;
+    maxFailedDocumentReads?: number;
+    maxRepeatedErrorPage?: number;
+    /** Domain vocabulary + copy for the stop message; neutral defaults when absent. */
+    vocabulary?: DocumentReadEvidenceVocabulary;
+}): DocumentReadLoopGuardDecision;
+export {};
+//# sourceMappingURL=document-read-loop-guard.d.ts.map

package/dist/documents/tools/document-read-loop-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-read-loop-guard.d.ts","sourceRoot":"","sources":["../../../src/documents/tools/document-read-loop-guard.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,KAAK,YAAY,GAAG;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC9C;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAsCD,MAAM,MAAM,6BAA6B,GAAG;IAC3C,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EACJ,sBAAsB,GACtB,0BAA0B,GAC1B,qBAAqB,GACrB,sBAAsB,GACtB,6BAA6B,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;CACxB,CAAC;AAgPF,wBAAgB,6BAA6B,CAC5C,SAAS,EAAE,QAAQ,CAAC,YAAY,CAAC,EACjC,OAAO,GAAE;IACR,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,oCAAoC,CAAC,EAAE,MAAM,CAAC;IAC9C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,mFAAmF;IACnF,UAAU,CAAC,EAAE,8BAA8B,CAAC;CACvC,GACJ,6BAA6B,CAgF/B"}

package/dist/documents/tools/document-read-loop-guard.js

@@ -0,0 +1,314 @@
+import * as z from 'zod/v4';
+const DEFAULT_FOUND_SUMMARY = 'I read the available pages from the requested document set.';
+const DEFAULT_NO_EVIDENCE_SUMMARY = 'The completed document.read pages did not expose legible content lines yet.';
+/** Whole-word, case-insensitive matcher over ESCAPED words (never a caller regex). */
+function subjectMatcher(words) {
+    const cleaned = (words ?? []).map((w) => w.trim()).filter((w) => w.length > 0);
+    if (cleaned.length === 0)
+        return null;
+    const escaped = cleaned.map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    return new RegExp(`\\b(${escaped.join('|')})\\b`, 'i');
+}
+const PageLikeSchema = z.object({
+    index: z.union([z.number(), z.string()]).optional(),
+    text: z.string().optional(),
+    status: z.string().optional(),
+    cacheKey: z.string().optional(),
+    message: z.string().optional()
+});
+const OutputWithPagesSchema = z.object({
+    pages: z.array(z.unknown())
+});
+const OutputErrorObjSchema = z.object({
+    message: z.string().optional()
+});
+const CallOutputSchema = z.object({
+    error: z.union([z.string(), OutputErrorObjSchema]).optional(),
+    ok: z.boolean().optional(),
+    message: z.string().optional()
+});
+const DEFAULT_MAX_EMPTY_DOCUMENT_READS = 5;
+const DEFAULT_MAX_REPEATED_PROCESSING_PAGE = 2;
+// A read recipe may SANCTION one re-read of a queued page ("queue other key
+// pages, then re-read the same page to retrieve its cached transcription"), so
+// once the model is already narrating an answer, allow that sanctioned re-read
+// and stop on the THIRD identical processing result — that is a poll loop.
+const DEFAULT_MAX_REPEATED_PROCESSING_PAGE_WITH_CONTENT = 3;
+// Total document.read budget for a single turn once content is streaming. A real
+// pass reads the index + a handful of target pages; dozens of reads with narration
+// in between is the live "keep re-reading and narrating progress" failure.
+const DEFAULT_MAX_DOCUMENT_READS = 12;
+// Distinct failed document.read calls before the turn stops re-trying.
+const DEFAULT_MAX_FAILED_DOCUMENT_READS = 3;
+// The same page erroring twice is already a deterministic dead end — the
+// error-marker cool-off serves the SAME failure back, so a third try cannot
+// succeed within the turn.
+const DEFAULT_MAX_REPEATED_ERROR_PAGE = 2;
+/**
+ * Terminal infrastructure signatures. When the OCR/vision executor is not
+ * registered in the serving runtime scope (ai-web `NoVisionModelError` →
+ * /api/internal/ocr 500), EVERY page read in the turn fails the same way —
+ * retrying cannot help and only produces the repeated-read loop. Stop on the
+ * FIRST occurrence with one deterministic blocker.
+ */
+const TERMINAL_INFRA_PATTERN = /NoVisionModelError|Generation executor not registered|no vision model|vision model.*not (?:registered|available|configured)/i;
+const VISION_UNAVAILABLE_BLOCKER = [
+    'I have to stop here: the drawing-reading service is unavailable right now, so I cannot read any sheets from this set.',
+    'This is a problem on our side — not with the drawing — and retrying will not help until it is fixed.',
+    'The imported drawings are safe. Please try again later, or ask me to report this to the team.',
+].join(' ');
+function readPages(output) {
+    const parsed = OutputWithPagesSchema.safeParse(output);
+    if (!parsed.success)
+        return [];
+    const pages = [];
+    for (const rawPage of parsed.data.pages) {
+        const page = PageLikeSchema.safeParse(rawPage);
+        if (page.success) {
+            pages.push(page.data);
+        }
+    }
+    return pages;
+}
+function pageStatus(page) {
+    return page.status ?? null;
+}
+function pageIndex(page) {
+    return page.index !== undefined ? String(page.index) : 'unknown';
+}
+function pageCacheKey(page) {
+    return page.cacheKey && page.cacheKey.length > 0 ? page.cacheKey : null;
+}
+function pageText(page) {
+    return page.text ?? '';
+}
+function pageMessage(page) {
+    return page.message ?? '';
+}
+/** Every error string a document.read call surfaces: the call-level error, an
+ *  output error envelope, and per-page error statuses/messages. */
+function readCallErrorTexts(call) {
+    const texts = [];
+    const callError = z.string().safeParse(call.error);
+    if (callError.success && callError.data.trim()) {
+        texts.push(callError.data);
+    }
+    const parsedOutput = CallOutputSchema.safeParse(call.output);
+    if (parsedOutput.success) {
+        const out = parsedOutput.data;
+        if (out.error) {
+            const strErr = z.string().safeParse(out.error);
+            if (strErr.success && strErr.data.trim()) {
+                texts.push(strErr.data);
+            }
+            else {
+                const objErr = OutputErrorObjSchema.safeParse(out.error);
+                if (objErr.success && objErr.data.message?.trim()) {
+                    texts.push(objErr.data.message);
+                }
+            }
+        }
+        if (out.ok === false && out.message?.trim()) {
+            texts.push(out.message);
+        }
+    }
+    for (const page of readPages(call.output)) {
+        if (pageStatus(page) !== 'error')
+            continue;
+        const message = pageMessage(page) || pageText(page);
+        if (message.trim())
+            texts.push(message);
+    }
+    return texts;
+}
+function isFailedRead(call) {
+    if (call.status === 'failed')
+        return true;
+    return readCallErrorTexts(call).length > 0;
+}
+function extractMarker(userMessage) {
+    if (!userMessage)
+        return null;
+    return userMessage.match(/\b[A-Z]{2,}-E2E-\d{8}-\d+\b/)?.[0] ?? null;
+}
+function cleanEvidenceLine(line) {
+    return line
+        .replace(/^\s{0,3}(?:[-*]|\d+\.)\s+/, '')
+        .replace(/\*\*/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function extractEvidenceBullets(pages, subjectWords) {
+    const bullets = [];
+    const seen = new Set();
+    const titlePattern = subjectMatcher(subjectWords);
+    // Detail markers are drawing-generic (dimensions, finishes, materials) — they
+    // describe how technical sheets are written, not what trade wrote them.
+    const dimensionPattern = /\b(\d+'\s*-|\d+\s*["”]|EQ\.?|TYP\.?|PLM\.?|SS\.?|O\.H\.?|finish|material|dimension)\b/i;
+    for (const page of pages) {
+        const lines = pageText(page)
+            .split(/\r?\n/)
+            .map(cleanEvidenceLine)
+            .filter((line) => line.length > 0 && !/^#+\s*/.test(line));
+        for (let i = 0; i < lines.length && bullets.length < 3; i += 1) {
+            const line = lines[i];
+            const next = lines.slice(i + 1, i + 4).find((candidate) => dimensionPattern.test(candidate));
+            // With a vocabulary: a line must name a subject. Without one: a line must
+            // carry detail — so the guard still quotes real evidence for any domain.
+            if (titlePattern) {
+                if (!titlePattern.test(line))
+                    continue;
+            }
+            else if (!dimensionPattern.test(line)) {
+                continue;
+            }
+            const combined = next && next !== line ? `${line}; ${next}` : line;
+            const clipped = combined.length > 220 ? `${combined.slice(0, 217)}...` : combined;
+            const key = clipped.toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            bullets.push(clipped);
+        }
+    }
+    return bullets;
+}
+function countMaxRepeats(pages) {
+    const counts = new Map();
+    for (const page of pages) {
+        const key = pageCacheKey(page) ?? `page:${pageIndex(page)}`;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return Math.max(0, ...counts.values());
+}
+function buildFallbackContent(input) {
+    const marker = extractMarker(input.userMessage);
+    const bullets = extractEvidenceBullets(input.readyPages, input.vocabulary?.subjectWords);
+    const processing = Array.from(new Set(input.processingPages.map(pageIndex))).join(', ');
+    const lines = [];
+    if (marker)
+        lines.push(marker);
+    lines.push(input.vocabulary?.foundSummary ?? DEFAULT_FOUND_SUMMARY);
+    if (bullets.length > 0) {
+        lines.push('');
+        lines.push('Evidence from completed document.read pages:');
+        for (const bullet of bullets)
+            lines.push(`- ${bullet}`);
+    }
+    else {
+        lines.push('');
+        lines.push(input.vocabulary?.noEvidenceSummary ?? DEFAULT_NO_EVIDENCE_SUMMARY);
+    }
+    if (processing) {
+        lines.push('');
+        lines.push(`Still processing: page ${processing}.`);
+    }
+    lines.push('');
+    lines.push(`I stopped after ${input.documentReadCount} document.read calls rather than keep re-reading queued sheets.`);
+    if (input.reason === 'repeated-processing-page') {
+        lines.push('The same queued page was returned as processing more than once.');
+    }
+    return lines.join('\n');
+}
+/** Short blocker for a reply the model already started streaming (appended by
+ *  the caller) or for an error stop — states only the one deterministic stop. */
+function buildShortBlocker(input) {
+    if (input.reason === 'repeated-processing-page') {
+        const processing = Array.from(new Set(input.processingPages.map(pageIndex))).join(', ');
+        return [
+            `I'm stopping here rather than keep re-checking the same sheet${processing ? ` (page ${processing})` : ''} — it is still being read in the background.`,
+            'Ask me again in a moment and I will pick up from its finished text.',
+        ].join(' ');
+    }
+    if (input.reason === 'repeated-error-page' || input.reason === 'document-read-errors') {
+        return [
+            'I hit repeated errors reading the drawing sheets and stopped retrying so this does not loop.',
+            input.lastErrorText ? `Last error: ${clipErrorText(input.lastErrorText)}.` : '',
+            'Tell me if you want me to try again later, or I can continue with the parts that do not need those sheets.',
+        ]
+            .filter(Boolean)
+            .join(' ');
+    }
+    return [
+        `I'm stopping after ${input.documentReadCount} sheet reads this turn rather than keep going.`,
+        'Tell me which sheets matter most and I will read just those next.',
+    ].join(' ');
+}
+function clipErrorText(text) {
+    const clean = text.replace(/\s+/g, ' ').trim();
+    return clean.length > 160 ? `${clean.slice(0, 157)}...` : clean;
+}
+export function evaluateDocumentReadLoopGuard(toolCalls, options = {}) {
+    const currentContent = options.currentContent?.trim() ?? '';
+    const hasContent = currentContent.length > 0;
+    const maxEmptyDocumentReads = options.maxEmptyDocumentReads ?? DEFAULT_MAX_EMPTY_DOCUMENT_READS;
+    const maxRepeatedProcessingPage = hasContent
+        ? (options.maxRepeatedProcessingPageWithContent ??
+            DEFAULT_MAX_REPEATED_PROCESSING_PAGE_WITH_CONTENT)
+        : (options.maxRepeatedProcessingPage ?? DEFAULT_MAX_REPEATED_PROCESSING_PAGE);
+    const maxDocumentReads = options.maxDocumentReads ?? DEFAULT_MAX_DOCUMENT_READS;
+    const maxFailedDocumentReads = options.maxFailedDocumentReads ?? DEFAULT_MAX_FAILED_DOCUMENT_READS;
+    const maxRepeatedErrorPage = options.maxRepeatedErrorPage ?? DEFAULT_MAX_REPEATED_ERROR_PAGE;
+    const documentReads = Array.from(toolCalls).filter((call) => call.name === 'document.read');
+    const pages = documentReads.flatMap((call) => readPages(call.output));
+    const readyPages = pages.filter((page) => pageStatus(page) === 'ready' && pageText(page).trim());
+    const processingPages = pages.filter((page) => pageStatus(page) === 'processing');
+    const errorPages = pages.filter((page) => pageStatus(page) === 'error');
+    const failedReads = documentReads.filter(isFailedRead);
+    const errorTexts = documentReads.flatMap(readCallErrorTexts);
+    const base = {
+        shouldStop: false,
+        documentReadCount: documentReads.length,
+        readyPageCount: readyPages.length,
+        processingPageCount: processingPages.length,
+        failedReadCount: failedReads.length,
+    };
+    if (documentReads.length === 0)
+        return base;
+    // Terminal infrastructure failure — stop on FIRST sighting, streamed content
+    // or not: every further read in this turn fails identically.
+    if (errorTexts.some((text) => TERMINAL_INFRA_PATTERN.test(text))) {
+        return {
+            ...base,
+            shouldStop: true,
+            reason: 'vision-executor-unavailable',
+            fallbackContent: VISION_UNAVAILABLE_BLOCKER,
+        };
+    }
+    const repeatedProcessing = countMaxRepeats(processingPages);
+    const repeatedError = countMaxRepeats(errorPages);
+    const reason = repeatedError >= maxRepeatedErrorPage
+        ? 'repeated-error-page'
+        : failedReads.length >= maxFailedDocumentReads
+            ? 'document-read-errors'
+            : repeatedProcessing >= maxRepeatedProcessingPage
+                ? 'repeated-processing-page'
+                : documentReads.length >= (hasContent ? maxDocumentReads : maxEmptyDocumentReads)
+                    ? 'document-read-budget'
+                    : undefined;
+    if (!reason)
+        return base;
+    const useShortBlocker = hasContent || reason === 'repeated-error-page' || reason === 'document-read-errors';
+    const fallbackContent = useShortBlocker
+        ? buildShortBlocker({
+            reason,
+            processingPages,
+            documentReadCount: documentReads.length,
+            lastErrorText: errorTexts.at(-1),
+        })
+        : buildFallbackContent({
+            userMessage: options.userMessage,
+            readyPages,
+            processingPages,
+            documentReadCount: documentReads.length,
+            reason,
+            vocabulary: options.vocabulary,
+        });
+    return {
+        ...base,
+        shouldStop: true,
+        reason,
+        fallbackContent,
+    };
+}
+//# sourceMappingURL=document-read-loop-guard.js.map

package/dist/documents/tools/document-read-loop-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-read-loop-guard.js","sourceRoot":"","sources":["../../../src/documents/tools/document-read-loop-guard.ts"],"names":[],"mappings":"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"}

package/dist/documents/tools/document-read.impl.d.ts

@@ -0,0 +1,77 @@
+/**
+ * document.read tool implementation.
+ *
+ * Cache-first orchestration for document reading:
+ *   1. Build a cache key from (ref, page, renderProfile, promptVersion)
+ *   2. Look up in the documents.page-cache manifest
+ *   3. Cache hit  → return stored markdown (+ cached rows when a schema read)
+ *   4. Cache miss → render the page PNG once via the scope-injected renderer
+ *                 → POST ai-web /api/internal/ocr (VISION OCR on the PNG) → markdown
+ *                 → when input.schema is set, ALSO POST ai-web
+ *                   /api/internal/document-extract (VISION extract on the SAME
+ *                   PNG) → rows
+ *                 → write markdown (+ rows) to the cache
+ *
+ * The rendered PNG is produced ONCE per page and fed to BOTH internal calls —
+ * extract is a vision read on the page image, not a re-parse of the OCR markdown.
+ *
+ * HTTP contracts (reconciled to the LIVE ai-web routes):
+ *
+ *   OCR endpoint — VISION OCR on a rasterized page image:
+ *     POST ${aiOrigin}/api/internal/ocr
+ *     Headers: Authorization: Bearer ${VIBES_INTERNAL_SERVICE_TOKEN}
+ *              Content-Type: application/json
+ *     Body: { image: string (raw base64 PNG), mimeType?, category?,
+ *             modelId?, modelName?, prompt? }
+ *     Response: { text: string, markdown: string, metadata: Record<string, unknown> }
+ *     (Source: apps/ai-web/src/routes/api/internal/ocr/+server.ts)
+ *
+ *   Extract endpoint — schema-driven VISION extract on the SAME page image:
+ *     POST ${aiOrigin}/api/internal/document-extract
+ *     Headers: Authorization: Bearer ${VIBES_INTERNAL_SERVICE_TOKEN}
+ *              Content-Type: application/json
+ *     Body: { image: string (raw base64 PNG), mimeType?, schema (REQUIRED),
+ *             vocabulary?: string[], rowContainerKeys?: string[], promptHint?: string, modelId?, modelName? }
+ *     Response: { rows: unknown[], raw: string, diagnostics: Record<string, unknown> }
+ *     (Source: apps/ai-web/src/routes/api/internal/document-extract/+server.ts)
+ *
+ * NOTE: there is no markdown-analyzer endpoint. When input.question is set WITHOUT
+ * input.schema, the impl returns the markdown path — the calling agent reads the
+ * page markdown to answer the question. A schema is required to get structured rows.
+ *
+ * A ref's `sourceRefreshUrl` is admitted against the declared destinations before
+ * the internal service credential goes to it (`./source-refresh.ts`).
+ *
+ * TODO(WS0): Wire VIBES_PDF_RENDER_ORIGIN for the consumer-scope renderer.
+ * TODO(WS0): Wire the platform CRUD endpoint /api/documents/page-cache (cloud-api adapter).
+ */
+import type { VibesRuntime } from '@vibesdotdev/kernel/api/runtime';
+import type { ToolCallContext } from '@vibesdotdev/kernel/schemas/tool-call';
+import type { ToolExecutionInput, ToolImplementation } from '@vibesdotdev/tools/kinds/tool';
+import type { DocumentReadOutput } from '../schemas/document-read.schema.ts';
+import { type DocumentPageCacheRecord } from '../schemas/page-cache.schema.ts';
+import type { DocumentRendererFactory } from '../render/render.interface.ts';
+/**
+ * Build a stable cache key for a (ref, page, renderProfile, promptVersion)
+ * tuple. Used to look up and write records in the documents.page-cache manifest.
+ */
+export declare function buildCacheKey(ref: {
+    providerId?: string;
+    path?: string;
+    url?: string;
+    documentId?: string;
+}, page: number, renderProfile: string, promptVersion: string): string;
+export declare function buildFoveatedPageJobId(storageCacheKey: string): Promise<string>;
+export declare function isProcessingCacheRecord(record: DocumentPageCacheRecord): boolean;
+export declare function isStaleProcessingCacheRecord(record: DocumentPageCacheRecord, nowMs?: number): boolean;
+/** A failure marker older than the cool-off (or missing/garbled failedAt —
+ *  legacy rows) is retryable: the read path re-renders + re-enqueues. */
+export declare function isRetryableErrorCacheRecord(record: DocumentPageCacheRecord, nowMs?: number): boolean;
+export declare class DocumentReadImplementation implements ToolImplementation {
+    /** Builds the renderer for each call's runtime (the plugin selects it by scope). */
+    private readonly rendererFor;
+    constructor(rendererFor: DocumentRendererFactory);
+    execute(rawInput: ToolExecutionInput, runtime: VibesRuntime, ctx: ToolCallContext): Promise<DocumentReadOutput>;
+}
+export declare function createDocumentReadTool(rendererFor: DocumentRendererFactory): ToolImplementation;
+//# sourceMappingURL=document-read.impl.d.ts.map

package/dist/documents/tools/document-read.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-read.impl.d.ts","sourceRoot":"","sources":["../../../src/documents/tools/document-read.impl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAOpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAU5F,OAAO,KAAK,EAEX,kBAAkB,EAElB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAEN,KAAK,uBAAuB,EAC5B,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAEX,uBAAuB,EAGvB,MAAM,+BAA+B,CAAC;AAiBvC;;;GAGG;AACH,wBAAgB,aAAa,CAC5B,GAAG,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,EAC9E,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,GACnB,MAAM,CAIR;AAOD,wBAAsB,sBAAsB,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAErF;AAoYD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAKhF;AAED,wBAAgB,4BAA4B,CAC3C,MAAM,EAAE,uBAAuB,EAC/B,KAAK,SAAa,GAChB,OAAO,CAOT;AAMD;yEACyE;AACzE,wBAAgB,2BAA2B,CAC1C,MAAM,EAAE,uBAAuB,EAC/B,KAAK,SAAa,GAChB,OAAO,CAOT;AAyuBD,qBAAa,0BAA2B,YAAW,kBAAkB;IACpE,oFAAoF;IACpF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;gBAE1C,WAAW,EAAE,uBAAuB;IAI1C,OAAO,CACZ,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE,eAAe,GAClB,OAAO,CAAC,kBAAkB,CAAC;CAkM9B;AAED,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,uBAAuB,GAAG,kBAAkB,CAE/F"}