@ai-matrx/agents 0.18.1 → 0.19.1

package/dist/sources/react/index.d.cts

@@ -204,6 +204,14 @@ interface SourceDraft {
     notes?: string[] | undefined;
     /** The person asked to wait for the clean version before anything runs. */
     waitForClean?: boolean | undefined;
+    /**
+     * Where the picked parts sit in the Source (label + pages), remembered when
+     * they are picked. A Source still being cleaned lists its raw pages; when the
+     * clean version lands its parts have NEW ids, and the pick is carried over by
+     * page from here (verify-3: "0 characters · 4 of 21 parts"). Persisted with
+     * the draft, so it survives a reload.
+     */
+    pickedParts?: SourcePickedPart[] | undefined;
     /**
      * What the person handed over, kept ONLY while the Source is still landing
      * (or failed) so a reload or a failure never loses it: the pasted text, the
@@ -212,6 +220,13 @@ interface SourceDraft {
      */
     input?: SourceIntakeInput | undefined;
 }
+/** One picked part as the person saw it: its id, its label, and the pages it covers. */
+interface SourcePickedPart {
+    id: string;
+    label: string;
+    /** First and last page it covers, when the Source has pages. */
+    pages?: [number, number] | undefined;
+}
 type SourceCardStatus = "pending" | "resolving" | "ready" | "error";
 /** One card: the draft, its lifecycle, and what the server measured. */
 interface SourceCardModel {
@@ -432,8 +447,14 @@ interface SourceSetController extends SourceSetActions {
     toSourceSet(options?: {
         targetModelId?: string | undefined;
     }): SourceSet;
-    /** Apply a set the review returned (forms, parts, caps, delivery). */
-    applySourceSet(set: SourceSet): void;
+    /**
+     * Apply a set the review returned (forms, parts, caps, delivery). Pass
+     * `reviewed` — the set sent INTO the review — and every Source removed there
+     * leaves the list too (only those; one that landed meanwhile stays).
+     */
+    applySourceSet(set: SourceSet, options?: {
+        reviewed?: SourceSet | undefined;
+    }): void;
     /** POST /sources/resolve — the grounded text for a generator, named as the cards name them. */
     resolve(options?: {
         targetModelId?: string | undefined;
@@ -591,15 +612,33 @@ interface SourceIntakeDeps<Body extends SourceLandingBodyBase = SourceLandingBod
 interface SourceIntake {
     addPastedText(text: string, name?: string): Promise<void>;
     addWebPage(url: string): Promise<void>;
-    /** A page the host's web picker already read (and the scraper landed); null id = land its text instead. */
+    /**
+     * A page the host's web picker already read (and the scraper landed); null id
+     * = land its text instead. `pendingId` = the card `beginWebPage` made when the
+     * read started — it is settled instead of a new card being added.
+     */
     addScrapedPage(page: {
         url: string;
         title: string;
         text: string;
         processedDocumentId: string | null;
-    }): Promise<void>;
+    }, pendingId?: string | null): Promise<void>;
+    /**
+     * The host's web picker STARTED reading a link: a card with the link kept
+     * appears at once, so a reload mid-read brings it back and lands it (verify-3
+     * 12a/12b: a reload while a page was read lost it, link and all). Finish it
+     * with `addScrapedPage(page, id)`; if the person drops the preview, remove it;
+     * if the picker goes away mid-read, `resume(card)` lands it through the web door.
+     */
+    beginWebPage(url: string): string;
     /** Files the host's uploader already uploaded. */
     addUploaded(files: readonly UploadedSourceFile[], kind: SourceKindId): Promise<void>;
+    /**
+     * A recording made in place (the Voice Pad) that is already written out: it
+     * lands as text, but it IS a recording — its card and review say "Recording",
+     * never "Pasted text" — and it keeps its name ("Recording 3:41 PM").
+     */
+    addRecordedText(text: string, name?: string): Promise<void>;
     /** A recording already uploaded — written out, then landed. */
     addUploadedRecording(file: UploadedSourceFile): Promise<void>;
     /** Something the person already has (Use existing / search). Returns false when already picked. */
@@ -690,7 +729,9 @@ interface UseSourceSetResult extends SourceSetActions {
         targetModelId?: string | undefined;
     }) => SourceSet;
     /** Apply a set the review page returned (forms, parts, caps, delivery). */
-    applySourceSet: (set: SourceSet) => void;
+    applySourceSet: (set: SourceSet, options?: {
+        reviewed?: SourceSet | undefined;
+    }) => void;
     /** POST /sources/resolve — the grounded text for a generator. */
     resolve: (options?: {
         targetModelId?: string | undefined;

package/dist/sources/react/index.d.ts

@@ -204,6 +204,14 @@ interface SourceDraft {
     notes?: string[] | undefined;
     /** The person asked to wait for the clean version before anything runs. */
     waitForClean?: boolean | undefined;
+    /**
+     * Where the picked parts sit in the Source (label + pages), remembered when
+     * they are picked. A Source still being cleaned lists its raw pages; when the
+     * clean version lands its parts have NEW ids, and the pick is carried over by
+     * page from here (verify-3: "0 characters · 4 of 21 parts"). Persisted with
+     * the draft, so it survives a reload.
+     */
+    pickedParts?: SourcePickedPart[] | undefined;
     /**
      * What the person handed over, kept ONLY while the Source is still landing
      * (or failed) so a reload or a failure never loses it: the pasted text, the
@@ -212,6 +220,13 @@ interface SourceDraft {
      */
     input?: SourceIntakeInput | undefined;
 }
+/** One picked part as the person saw it: its id, its label, and the pages it covers. */
+interface SourcePickedPart {
+    id: string;
+    label: string;
+    /** First and last page it covers, when the Source has pages. */
+    pages?: [number, number] | undefined;
+}
 type SourceCardStatus = "pending" | "resolving" | "ready" | "error";
 /** One card: the draft, its lifecycle, and what the server measured. */
 interface SourceCardModel {
@@ -432,8 +447,14 @@ interface SourceSetController extends SourceSetActions {
     toSourceSet(options?: {
         targetModelId?: string | undefined;
     }): SourceSet;
-    /** Apply a set the review returned (forms, parts, caps, delivery). */
-    applySourceSet(set: SourceSet): void;
+    /**
+     * Apply a set the review returned (forms, parts, caps, delivery). Pass
+     * `reviewed` — the set sent INTO the review — and every Source removed there
+     * leaves the list too (only those; one that landed meanwhile stays).
+     */
+    applySourceSet(set: SourceSet, options?: {
+        reviewed?: SourceSet | undefined;
+    }): void;
     /** POST /sources/resolve — the grounded text for a generator, named as the cards name them. */
     resolve(options?: {
         targetModelId?: string | undefined;
@@ -591,15 +612,33 @@ interface SourceIntakeDeps<Body extends SourceLandingBodyBase = SourceLandingBod
 interface SourceIntake {
     addPastedText(text: string, name?: string): Promise<void>;
     addWebPage(url: string): Promise<void>;
-    /** A page the host's web picker already read (and the scraper landed); null id = land its text instead. */
+    /**
+     * A page the host's web picker already read (and the scraper landed); null id
+     * = land its text instead. `pendingId` = the card `beginWebPage` made when the
+     * read started — it is settled instead of a new card being added.
+     */
     addScrapedPage(page: {
         url: string;
         title: string;
         text: string;
         processedDocumentId: string | null;
-    }): Promise<void>;
+    }, pendingId?: string | null): Promise<void>;
+    /**
+     * The host's web picker STARTED reading a link: a card with the link kept
+     * appears at once, so a reload mid-read brings it back and lands it (verify-3
+     * 12a/12b: a reload while a page was read lost it, link and all). Finish it
+     * with `addScrapedPage(page, id)`; if the person drops the preview, remove it;
+     * if the picker goes away mid-read, `resume(card)` lands it through the web door.
+     */
+    beginWebPage(url: string): string;
     /** Files the host's uploader already uploaded. */
     addUploaded(files: readonly UploadedSourceFile[], kind: SourceKindId): Promise<void>;
+    /**
+     * A recording made in place (the Voice Pad) that is already written out: it
+     * lands as text, but it IS a recording — its card and review say "Recording",
+     * never "Pasted text" — and it keeps its name ("Recording 3:41 PM").
+     */
+    addRecordedText(text: string, name?: string): Promise<void>;
     /** A recording already uploaded — written out, then landed. */
     addUploadedRecording(file: UploadedSourceFile): Promise<void>;
     /** Something the person already has (Use existing / search). Returns false when already picked. */
@@ -690,7 +729,9 @@ interface UseSourceSetResult extends SourceSetActions {
         targetModelId?: string | undefined;
     }) => SourceSet;
     /** Apply a set the review page returned (forms, parts, caps, delivery). */
-    applySourceSet: (set: SourceSet) => void;
+    applySourceSet: (set: SourceSet, options?: {
+        reviewed?: SourceSet | undefined;
+    }) => void;
     /** POST /sources/resolve — the grounded text for a generator. */
     resolve: (options?: {
         targetModelId?: string | undefined;

package/dist/sources/react/index.js

@@ -100,12 +100,12 @@ function deliveryPatch(delivery) {
 var DELIVERY_WORDS = {
   direct: {
     label: "Include the text",
-    hint: "The text is handed to the AI with your request, so it reads all of it before it starts.",
+    hint: "Sent in full",
     summary: "Text included"
   },
   context: {
     label: "Let the AI look it up",
-    hint: "Nothing is sent up front. The AI opens this Source and reads the parts it needs while it works \u2014 best for very large Sources.",
+    hint: "Read as needed",
     summary: "Looked up when needed"
   }
 };
@@ -128,6 +128,13 @@ function fitDelivery(ref, deliveries) {
 
 // sources/runtime/partsSearch.ts
 var RANGE_RE = /^(\d+)\s*(?:-|–|—|to)\s*(\d+)$/;
+var SPAN_RE = /(\d+)\s*[–—-]\s*(\d+)/;
+function partPages(part) {
+  if (part.page === void 0 || part.page === null) return null;
+  const span = /^pages?\s/i.test(part.label) ? SPAN_RE.exec(part.label) : null;
+  if (span) return [Number(span[1]), Number(span[2])];
+  return [part.page, part.page];
+}
 function isWordQuery(query) {
   const q = query.trim().toLowerCase();
   return q.length > 0 && !/^\d+$/.test(q) && !RANGE_RE.test(q);
@@ -146,7 +153,7 @@ function resumableInput(draft) {
     case "youtube":
       return input.url?.trim() ? input : null;
     case "audio":
-      return input.fileId ? input : null;
+      return input.fileId || input.text?.trim() ? input : null;
     default:
       return null;
   }
@@ -161,12 +168,12 @@ function reloadedCard(draft, status) {
     return { action: "reoffer", sentence: uploadCutOffSentence(draft) };
   return { action: "lost", sentence: RELOADED_WHILE_ADDING };
 }
-var NOT_KEPT_FOR_RELOAD = "Too large to keep on this device, so it will not come back if the page reloads before it is added.";
+var NOT_KEPT_FOR_RELOAD = "Too large to restore if the page reloads before it is added.";
 var WAITING_FOR_ORGANIZATION = "Waiting for an organization \u2014 choose one and this continues by itself.";
 var KEEP_WAITING_FOR_ORGANIZATION = "Read. Waiting for an organization to keep it \u2014 choose one and it is kept by itself.";
 
 // sources/runtime/fileSource.ts
-var UNREADABLE = "The file is stored, but it could not be read into a Source, so nothing in it can be used yet. Remove it, or add a different copy (a PDF, Word file or plain text reads best).";
+var UNREADABLE = "Can't read this file \u2014 add a PDF, Word or text copy.";
 function nextFileStep(status, ctx) {
   const pdId = status?.processed_document_id ?? null;
   if (pdId) return { do: "keep", processedDocumentId: pdId };
@@ -174,7 +181,7 @@ function nextFileStep(status, ctx) {
   if (status?.state === "failed")
     return {
       do: "unreadable",
-      reason: status.error?.message ? `The file could not be read: ${status.error.message}. Remove it, or add it again.` : UNREADABLE
+      reason: status.error?.message ? `Can't read this file: ${status.error.message}. Add it again.` : UNREADABLE
     };
   if (!ctx.started) return { do: "start" };
   return { do: "unreadable", reason: UNREADABLE };
@@ -195,6 +202,8 @@ function fileCardHeldForOrganization(card, activeOrganizationId, fileOrganizatio
 
 // sources/runtime/state.ts
 var EMPTY_SOURCE_SET_STATE = Object.freeze({ cards: Object.freeze([]), topic: "" });
+var PARTS_MATCHED_BY_PAGE = "The clean version is ready \u2014 your parts were matched to it by page.";
+var PARTS_NOT_MATCHED = "The clean version is ready, but your parts could not be matched to it \u2014 choose parts again. Until then the whole Source goes in.";
 var SAME_SOURCE_AGAIN = "You added this again \u2014 it is the same Source, so it is listed once.";
 function isSourceDraft(value) {
   return !!value && typeof value === "object" && typeof value.kind === "string" && typeof value.label === "string";
@@ -261,7 +270,7 @@ function settleCard(state, id, patch, options = {}) {
   }));
 }
 function failCard(state, id, sentence) {
-  return replaceCard(state, id, (c) => ({ ...c, status: "error", error: sentence }));
+  return replaceCard(state, id, (c) => ({ ...c, status: "error", error: sentence, manifest: null }));
 }
 function restartCard(state, id) {
   return replaceCard(state, id, (c) => ({ ...c, status: "resolving", error: null }));
@@ -277,7 +286,68 @@ function updateCardRef(state, id, options) {
   return replaceCard(state, id, (c) => {
     if (!c.draft.ref) return c;
     const ref = createSourceRef(c.draft.ref.resource_type, c.draft.ref.resource_id, { ...c.draft.ref, ...options });
-    return { ...c, draft: { ...c.draft, ref } };
+    return rememberPickedParts({ ...c, draft: { ...c.draft, ref } });
+  });
+}
+function rememberPickedParts(card) {
+  const ids = card.draft.ref?.include_segments ?? [];
+  if (ids.length === 0) {
+    return card.draft.pickedParts === void 0 ? card : { ...card, draft: { ...card.draft, pickedParts: void 0 } };
+  }
+  const segments = card.manifest?.segments ?? [];
+  const known = new Map((card.draft.pickedParts ?? []).map((p) => [p.id, p]));
+  const picked = [];
+  for (const id of ids) {
+    const segment = segments.find((s) => s.id === id);
+    if (segment) {
+      const pages = partPages(segment);
+      picked.push({ id, label: segment.label, ...pages ? { pages } : {} });
+    } else {
+      const before = known.get(id);
+      if (before) picked.push(before);
+    }
+  }
+  return { ...card, draft: { ...card.draft, pickedParts: picked.length ? picked : void 0 } };
+}
+function withNote(notes, note, drop = []) {
+  const kept = (notes ?? []).filter((n) => n !== note && !drop.includes(n));
+  return [...kept, note];
+}
+function carryPickedParts(card, entry) {
+  const ref = card.draft.ref;
+  const picked = ref?.include_segments ?? [];
+  const segments = entry.segments ?? [];
+  if (!ref || picked.length === 0 || segments.length === 0) return card;
+  const ids = new Set(segments.map((s) => s.id));
+  const stale = picked.filter((id) => !ids.has(id));
+  if (stale.length === 0) return card;
+  const remembered = new Map((card.draft.pickedParts ?? []).map((p) => [p.id, p]));
+  const oldSegments = card.manifest?.segments ?? [];
+  const spans = [];
+  let unknown = 0;
+  for (const id of stale) {
+    const old = oldSegments.find((s) => s.id === id);
+    const pages = remembered.get(id)?.pages ?? (old ? partPages(old) : null);
+    if (pages) spans.push(pages);
+    else unknown += 1;
+  }
+  const keep = new Set(picked.filter((id) => ids.has(id)));
+  for (const segment of segments) {
+    const pages = partPages(segment);
+    if (pages && spans.some(([from, to]) => pages[0] <= to && pages[1] >= from)) keep.add(segment.id);
+  }
+  const nextIds = segments.filter((s) => keep.has(s.id)).map((s) => s.id);
+  const matched = unknown === 0 && nextIds.length > 0;
+  const nextRef = createSourceRef(ref.resource_type, ref.resource_id, {
+    ...ref,
+    include_segments: matched ? nextIds : void 0
+  });
+  const note = matched ? PARTS_MATCHED_BY_PAGE : PARTS_NOT_MATCHED;
+  const other = matched ? PARTS_NOT_MATCHED : PARTS_MATCHED_BY_PAGE;
+  return rememberPickedParts({
+    ...card,
+    manifest: entry,
+    draft: { ...card.draft, ref: nextRef, notes: withNote(card.draft.notes, note, [other]) }
   });
 }
 function setCardWaitForClean(state, id, wait) {
@@ -286,14 +356,24 @@ function setCardWaitForClean(state, id, wait) {
 function setSourceTopic(state, topic) {
   return state.topic === topic ? state : { ...state, topic };
 }
-function applyReviewedSourceSet(state, set) {
+function removedInReview(reviewed, answer) {
+  const kept = new Set(answer.sources.map(sourceKey));
+  return new Set(reviewed.sources.map(sourceKey).filter((k) => !kept.has(k)));
+}
+function applyReviewedSourceSet(state, set, reviewed) {
   let next = state;
-  for (const card of state.cards) {
+  if (reviewed) {
+    const removed = removedInReview(reviewed, set);
+    for (const card of state.cards) {
+      if (card.draft.ref && removed.has(sourceKey(card.draft.ref))) next = removeCard(next, card.id);
+    }
+  }
+  for (const card of next.cards) {
     const ref = card.draft.ref;
     if (!ref) continue;
     const match = set.sources.find((r) => sameSourceRef(r, ref));
     if (!match) continue;
-    next = replaceCard(next, card.id, (c) => ({ ...c, draft: { ...c.draft, ref: match } }));
+    next = replaceCard(next, card.id, (c) => rememberPickedParts({ ...c, draft: { ...c.draft, ref: match } }));
   }
   return set.topic !== void 0 ? setSourceTopic(next, set.topic) : next;
 }
@@ -303,7 +383,13 @@ function applyManifest(state, manifest) {
     const ref = card.draft.ref;
     if (!ref || card.status !== "ready") continue;
     const entry = manifest.sources.find((e) => sameSourceRef(e.ref, ref));
-    if (entry) next = replaceCard(next, card.id, (c) => ({ ...c, manifest: entry }));
+    if (!entry) continue;
+    next = replaceCard(next, card.id, (c) => {
+      const carried = carryPickedParts(c, entry);
+      if (carried !== c) return carried;
+      const measured = { ...c, manifest: entry };
+      return c.draft.ref?.include_segments?.length && !c.draft.pickedParts ? rememberPickedParts(measured) : measured;
+    });
   }
   return next;
 }
@@ -498,8 +584,8 @@ function createSourceSetController(adapter) {
     hasRef: (resourceType, resourceId) => hasSourceRef(store.getState(), resourceType, resourceId),
     liveCount: () => store.getState().cards.length,
     toSourceSet: (options = {}) => selectSourceSet(store.getState(), options),
-    applySourceSet(set) {
-      commit(applyReviewedSourceSet(store.getState(), set));
+    applySourceSet(set, options = {}) {
+      commit(applyReviewedSourceSet(store.getState(), set, options.reviewed));
     },
     async manifest() {
       const refs = readySourceRefs(store.getState());
@@ -784,20 +870,45 @@ function createSourceIntake(set, deps) {
       });
       await hold(() => landPaste(id, trimmed, name));
     },
+    async addRecordedText(text, name) {
+      const trimmed = text.trim();
+      if (!trimmed) return;
+      const max = deps.maxKeptChars();
+      const kept = max !== null && trimmed.length <= max;
+      const id = set.addPending({
+        kind: "audio",
+        label: name?.trim() || "Recording",
+        origin: "Recording",
+        input: kept ? { text: trimmed, name } : void 0,
+        notes: kept ? void 0 : [NOT_KEPT_FOR_RELOAD]
+      });
+      await hold(() => landPaste(id, trimmed, name));
+    },
     async addWebPage(raw) {
       const url = /^https?:\/\//i.test(raw.trim()) ? raw.trim() : `https://${raw.trim()}`;
       const id = set.addPending({ kind: "web", label: hostOf(url), origin: url, input: { url } });
       await hold(() => landWebPage(id, url));
     },
-    async addScrapedPage(page) {
+    beginWebPage(raw) {
+      const url = /^https?:\/\//i.test(raw.trim()) ? raw.trim() : `https://${raw.trim()}`;
+      return set.addPending({ kind: "web", label: hostOf(url), origin: url, input: { url } });
+    },
+    async addScrapedPage(page, pendingId) {
       const label = page.title || hostOf(page.url);
+      const cardFor = () => {
+        if (pendingId && set.restart(pendingId)) {
+          set.updateDraft(pendingId, { label, origin: page.url, input: { url: page.url } });
+          return pendingId;
+        }
+        return set.addPending({ kind: "web", label, origin: page.url, input: { url: page.url } });
+      };
       if (!page.processedDocumentId) {
-        const id2 = set.addPending({ kind: "web", label, origin: page.url, input: { url: page.url } });
+        const id2 = cardFor();
         await hold(() => landPaste(id2, page.text, label));
         return;
       }
       const pdId = page.processedDocumentId;
-      const id = set.addPending({ kind: "web", label, origin: page.url, input: { url: page.url } });
+      const id = cardFor();
       await hold(async () => {
         let notes = [];
         try {
@@ -872,7 +983,8 @@ function createSourceIntake(set, deps) {
           return true;
         }
         case "audio":
-          void transcribeRecording(card.id, input.fileId ?? "", card.draft.label);
+          if (input.fileId) void transcribeRecording(card.id, input.fileId, card.draft.label);
+          else void landPaste(card.id, (input.text ?? "").trim(), input.name);
           return true;
         default:
           return false;