@tangle-network/agent-app 0.44.7 → 0.44.9

package/dist/work-product/index.js

@@ -1,7 +1,7 @@
 import {
   parseReviewQueueItem,
   projectReviewQueue
-} from "../chunk-UP33Z633.js";
+} from "../chunk-ZRSUCTST.js";
 import {
   isWorkProductStatus,
   parseAgentCheckInput,
@@ -11,7 +11,7 @@ import {
   persistedPartToWorkProduct,
   unresolvedBlockingExceptions,
   workProductToPersistedPart
-} from "../chunk-F2CBC4DY.js";
+} from "../chunk-V3HO43PG.js";
 import {
   ToolInputError,
   defineAppTool
@@ -403,6 +403,20 @@ function sourceContainsQuote(sourceText, quote) {
   if (normalizedQuote.length === 0) return false;
   return normalizeQuoteText(sourceText).includes(normalizedQuote);
 }
+function sliceSourceSpan(sourceText, span) {
+  for (const field of ["start", "end"]) {
+    const value = span[field];
+    if (!Number.isInteger(value)) return { ok: false, failure: { reason: "not_integer", field } };
+    if (value < 0) return { ok: false, failure: { reason: "negative", field } };
+  }
+  if (span.end <= span.start) return { ok: false, failure: { reason: "inverted" } };
+  if (span.end > sourceText.length) {
+    return { ok: false, failure: { reason: "out_of_range", totalChars: sourceText.length } };
+  }
+  const quote = sourceText.slice(span.start, span.end);
+  if (quote.trim().length === 0) return { ok: false, failure: { reason: "blank" } };
+  return { ok: true, quote };
+}
 
 // src/work-product/tools.ts
 var MAX_WORK_PRODUCT_BATCH = 50;
@@ -452,17 +466,61 @@ async function resolveDraft(service, config, scopeKey, ctx) {
     provenance: stampProvenance(config.provenance(ctx), config.now)
   });
 }
-async function assertQuotesOccurInSources(config, entries, ctx) {
+function spanErrorDetail(failure) {
+  switch (failure.reason) {
+    case "not_integer":
+      return `${failure.field} must be a whole character offset.`;
+    case "negative":
+      return `${failure.field} must not be negative.`;
+    case "inverted":
+      return "end must be greater than start \u2014 the range is half-open [start, end).";
+    case "out_of_range":
+      return `end is past the end of the document, which is ${failure.totalChars} characters. Offsets are absolute in the whole document: when you read with an offset, add that offset to the position within the returned text.`;
+    case "blank":
+      return "that range is only whitespace. Widen it to the characters that carry the value.";
+  }
+}
+async function resolveEvidenceQuotes(config, entries, ctx) {
   const readSourceText = config.readSourceText;
-  if (!readSourceText) return;
   const texts = /* @__PURE__ */ new Map();
+  const readText = async (ref) => {
+    if (!texts.has(ref)) texts.set(ref, await readSourceText(ref, ctx));
+    return texts.get(ref) ?? null;
+  };
   for (let index = 0; index < entries.length; index += 1) {
     const entry = entries[index];
+    const span = entry.locator.span;
     const quote = entry.locator.quote;
+    if (span) {
+      if (!readSourceText) {
+        throw new ToolInputError(
+          "span_unsupported",
+          `entries[${index}].locator.span: this deployment cannot read source text, so a span cannot be resolved into a quote. Record the entry without locator.span.`,
+          500
+        );
+      }
+      const text2 = await readText(entry.sourceRef);
+      if (text2 === null) {
+        throw new ToolInputError(
+          "unverifiable_quote",
+          `entries[${index}].locator.span: "${entry.sourceRef}" has no readable text, so the span cannot be resolved. Record the entry without locator.span or locator.quote and state the basis in claim.`
+        );
+      }
+      const sliced = sliceSourceSpan(text2, span);
+      if (!sliced.ok) {
+        throw new ToolInputError(
+          "invalid_span",
+          `entries[${index}].locator.span [${span.start}, ${span.end}) into "${entry.sourceRef}": ${spanErrorDetail(sliced.failure)}`
+        );
+      }
+      entry.locator.quote = sliced.quote;
+      entry.locator.quoteBasis = "span";
+      continue;
+    }
     if (quote === void 0 || quote.trim().length === 0) continue;
-    if (!texts.has(entry.sourceRef)) texts.set(entry.sourceRef, await readSourceText(entry.sourceRef, ctx));
-    const text = texts.get(entry.sourceRef);
-    if (text === null || text === void 0) {
+    if (!readSourceText) continue;
+    const text = await readText(entry.sourceRef);
+    if (text === null) {
       throw new ToolInputError(
         "unverifiable_quote",
         `entries[${index}].locator.quote: "${entry.sourceRef}" has no readable text, so the quote cannot be verified. Record the entry without locator.quote and state the basis in claim.`
@@ -471,9 +529,10 @@ async function assertQuotesOccurInSources(config, entries, ctx) {
     if (!sourceContainsQuote(text, quote)) {
       throw new ToolInputError(
         "quote_not_found",
-        `entries[${index}].locator.quote: ${JSON.stringify(quote)} does not occur in "${entry.sourceRef}". Copy the supporting line character-for-character out of that document, or \u2014 if this value is COMPUTED rather than read \u2014 omit locator.quote and state the computation in claim.`
+        `entries[${index}].locator.quote: ${JSON.stringify(quote)} does not occur in "${entry.sourceRef}". Cite locator.span {start, end} instead \u2014 the character range you read it at, which this platform slices out of the document itself so the text is right by construction. If the value is COMPUTED rather than read, omit both and state the computation in claim.`
       );
     }
+    entry.locator.quoteBasis = "model";
   }
 }
 async function summarizeQuoteVerification(config, evidence, ctx) {
@@ -481,6 +540,7 @@ async function summarizeQuoteVerification(config, evidence, ctx) {
   if (!readSourceText) return void 0;
   const texts = /* @__PURE__ */ new Map();
   let verified = 0;
+  let spanAnchored = 0;
   let withoutQuote = 0;
   const failed = [];
   for (const entry of evidence) {
@@ -491,10 +551,23 @@ async function summarizeQuoteVerification(config, evidence, ctx) {
     }
     if (!texts.has(entry.sourceRef)) texts.set(entry.sourceRef, await readSourceText(entry.sourceRef, ctx));
     const text = texts.get(entry.sourceRef);
-    if (typeof text === "string" && sourceContainsQuote(text, quote)) verified += 1;
+    if (typeof text !== "string") {
+      failed.push(entry.id);
+      continue;
+    }
+    const span = entry.locator.span;
+    if (span) {
+      const sliced = sliceSourceSpan(text, span);
+      if (sliced.ok && sliced.quote === quote) {
+        verified += 1;
+        spanAnchored += 1;
+      } else failed.push(entry.id);
+      continue;
+    }
+    if (sourceContainsQuote(text, quote)) verified += 1;
     else failed.push(entry.id);
   }
-  return { verified, withoutQuote, failed };
+  return { verified, spanAnchored, withoutQuote, failed };
 }
 function buildWorkProductTools(config) {
   const service = createWorkProductService({
@@ -504,7 +577,7 @@ function buildWorkProductTools(config) {
   });
   const upsertEvidence = defineAppTool({
     name: "upsert_evidence",
-    description: "Record source\u2192field lineage for the current work product, incrementally as you find it. Each entry links a source document (sourceRef + locator) to one artifact target and states the claim it supports. Re-emitting an entry id replaces that entry. Address the work product by scopeKey; the first call creates the draft.",
+    description: "Record source\u2192field lineage for the current work product, incrementally as you find it. Each entry links a source document (sourceRef + locator) to one artifact target and states the claim it supports. Cite by locator.span {start, end} \u2014 the character range you read the value at \u2014 and the platform slices the supporting quote out of the document for you. Re-emitting an entry id replaces that entry. Address the work product by scopeKey; the first call creates the draft.",
     parameters: {
       type: "object",
       properties: {
@@ -523,9 +596,18 @@ function buildWorkProductTools(config) {
                 properties: {
                   page: { type: "number" },
                   range: { type: "string", description: "Free-form location: 'L120-L134' | 'B7' | '\xB64'." },
+                  span: {
+                    type: "object",
+                    description: "PREFERRED. The character range you read the value at, as absolute offsets into the whole document: start is the first character, end is one past the last. If you read with an offset, add that offset to the position within the text you got back. The platform slices the quote out of the document itself and stores it, and returns it to you \u2014 you never retype source text, so the citation cannot be wrong. Use this whenever the value was READ from a document.",
+                    properties: {
+                      start: { type: "integer", minimum: 0 },
+                      end: { type: "integer", minimum: 1 }
+                    },
+                    required: ["start", "end"]
+                  },
                   quote: {
                     type: "string",
-                    description: "Verbatim supporting quote \u2014 copied character-for-character out of the source, not retyped, reformatted, or summarised. The platform checks it occurs in the document and REFUSES the entry if it does not. For a value you COMPUTED rather than read, omit this field and state the computation in claim."
+                    description: "Fallback for sources that cannot give you character offsets: the supporting text copied character-for-character. The platform checks it occurs in the document and REFUSES the entry if it does not. Prefer span. For a value you COMPUTED rather than read, omit both and state the computation in claim."
                   }
                 }
               },
@@ -557,10 +639,24 @@ function buildWorkProductTools(config) {
           );
         }
       }
-      await assertQuotesOccurInSources(config, entries, ctx);
+      await resolveEvidenceQuotes(config, entries, ctx);
       const draft = await resolveDraft(service, config, scopeKey, ctx);
       const record = await unwrap(() => service.upsertEvidence(draft.id, entries), "evidence_rejected");
-      return { workProductId: record.id, version: record.version, evidenceCount: record.evidence.length };
+      return {
+        workProductId: record.id,
+        version: record.version,
+        evidenceCount: record.evidence.length,
+        // Echo what was actually STORED for the entries in this call. A span
+        // citation's quote is produced here, not sent here, so the model must
+        // be able to see the text its offsets selected — that is how it
+        // notices an off-by-a-line span without a second read.
+        entries: entries.map((entry) => ({
+          id: entry.id,
+          target: entry.target,
+          ...entry.locator.quote === void 0 ? {} : { quote: entry.locator.quote },
+          ...entry.locator.quoteBasis === void 0 ? {} : { quoteBasis: entry.locator.quoteBasis }
+        }))
+      };
     }
   });
   const flagException = defineAppTool({
@@ -692,7 +788,7 @@ function buildWorkProductTools(config) {
           id: QUOTE_VERIFICATION_CHECK,
           name: QUOTE_VERIFICATION_CHECK,
           passed: quotes.failed.length === 0,
-          detail: quotes.failed.length === 0 ? `${quotes.verified}/${quoted} quoted evidence entries verified against their source; ${quotes.withoutQuote} recorded without a quote` : `Unverifiable quotes on: ${quotes.failed.join(", ")}`,
+          detail: quotes.failed.length === 0 ? `${quotes.verified}/${quoted} quoted evidence entries verified against their source (${quotes.spanAnchored} platform-sliced from a source span, ${quotes.verified - quotes.spanAnchored} model-quoted and proved to occur); ${quotes.withoutQuote} recorded without a quote` : `Unverifiable quotes on: ${quotes.failed.join(", ")}`,
           source: "platform"
         });
         if (quotes.failed.length > 0) {
@@ -707,11 +803,21 @@ function buildWorkProductTools(config) {
         const targets = config.materialTargets(artifact);
         const covered = new Set(draft.evidence.map((entry) => entry.target));
         const missing = targets.filter((target) => !covered.has(target));
+        const anchoredTargets = new Set(
+          draft.evidence.filter((entry) => entry.locator.quoteBasis !== void 0).map((entry) => entry.target)
+        );
+        const spanTargets = new Set(
+          draft.evidence.filter((entry) => entry.locator.quoteBasis === "span").map((entry) => entry.target)
+        );
+        const present = targets.filter((target) => covered.has(target));
+        const unanchored = present.filter((target) => !anchoredTargets.has(target));
+        const spanCount = present.filter((target) => spanTargets.has(target)).length;
+        const breakdown = `${spanCount} span-anchored, ${present.length - spanCount - unanchored.length} quote-verified, ${unanchored.length} claim-only`;
         const coverage = {
           id: EVIDENCE_COVERAGE_CHECK,
           name: EVIDENCE_COVERAGE_CHECK,
-          passed: missing.length === 0,
-          detail: missing.length === 0 ? `${targets.length}/${targets.length} material targets evidenced` : `Missing evidence for: ${missing.join(", ")}`,
+          passed: missing.length === 0 && !(config.requireAnchoredEvidence && unanchored.length > 0),
+          detail: missing.length > 0 ? `Missing evidence for: ${missing.join(", ")}` : config.requireAnchoredEvidence && unanchored.length > 0 ? `No source anchor for: ${unanchored.join(", ")}` : `${targets.length}/${targets.length} material targets evidenced (${breakdown})`,
           source: "platform"
         };
         checks.unshift(coverage);
@@ -722,6 +828,13 @@ function buildWorkProductTools(config) {
             `Cannot submit: material targets lack evidence: ${missing.join(", ")}. Add upsert_evidence entries targeting each, then resubmit.`
           );
         }
+        if (config.requireAnchoredEvidence && unanchored.length > 0) {
+          await unwrap(() => service.recordChecks(draft.id, checks), "checks_rejected");
+          throw new ToolInputError(
+            "evidence_not_anchored",
+            `Cannot submit: these material targets have an evidence row but no source anchor: ${unanchored.join(", ")}. Re-emit each with locator.span {start, end} \u2014 the character range in the document you read the value at. The platform slices the quote out of the document itself, so you never retype source text.`
+          );
+        }
       }
       const provenance = stampProvenance(config.provenance(ctx), config.now);
       const record = await unwrap(
@@ -851,6 +964,7 @@ export {
   parseReviewQueueItem,
   persistedPartToWorkProduct,
   projectReviewQueue,
+  sliceSourceSpan,
   sourceContainsQuote,
   stampProvenance,
   unresolvedBlockingExceptions,