@mindstudio-ai/agent 0.1.139 → 0.1.140

package/dist/index.d.ts

@@ -2332,6 +2332,21 @@ interface SearchExplain {
     lexical: BranchPosition | null;
     matchedVia: 'dense' | 'lexical' | 'both';
 }
+/** One passage of a listing ({@link DataSource.passages}): a search hit without the ranking. */
+interface DataSourcePassage {
+    /** The chunk, prefixed with its heading path for context. */
+    text: string;
+    /** The ids the passage carries: its document's, and those its text names from the dictionary. */
+    entities: string[];
+    citation: Citation;
+}
+/** A page of {@link DataSource.passages}. */
+interface DataSourcePassagePage {
+    passages: DataSourcePassage[];
+    /** Pass back for the next page; null after the last. */
+    nextCursor: string | null;
+    latencyMs: number;
+}
 interface SearchHit {
     /**
      * Relevance of this hit. Comparable within a response, not across them —
@@ -2818,9 +2833,14 @@ interface DictionaryReport {
     names: number;
     /** Names more than one id claims: a passage naming one is tagged with every claimant. */
     ambiguousNames: number;
-    /** The names (as matched: folded, separators dropped) the most ids claim. */
+    /**
+     * The names the most ids claim: `name` as you pushed it (one of them, when
+     * several fold alike), `key` as the linker matches it (folded, separators
+     * dropped), and how many ids claim it.
+     */
     mostClaimed: {
         key: string;
+        name?: string;
         ids: number;
     }[];
     /**
@@ -2959,7 +2979,8 @@ declare class DataSource {
      * it is who or what was written about then. No filter covers the corpus.
      * `chunks` is how many matching passages carry each id, not documents: a
      * long document's passages each count. Approximate counts, ordered most
-     * first; `limit` defaults to 20, at most 100.
+     * first; `limit` defaults to 20, at most 1,000. One document's entities:
+     * `{ filter: { documentIds: [id] } }`.
      *
      * Shares the search rate limit (300/minute per app), and shows the same
      * `index_warming` / `index_building` as search while a corpus loads.
@@ -3075,6 +3096,38 @@ declare class DataSource {
         limit?: number;
         order?: 'oldest' | 'newest';
     }): Promise<DataSourceDocumentPage>;
+    /**
+     * One page of the passages matching a filter, unranked: every page that
+     * mentions an asset (`{ entities: ['P-1004A'] }`), every passage holding a
+     * phrase, every chunk of some documents. Where {@link search} ranks and
+     * stops at its top results and {@link count} gives a number, this lists
+     * them all. Passages come document by document, each document's in order;
+     * pass `nextCursor` back for the next page, which is null after the last.
+     * `limit` defaults to 50, at most 200.
+     *
+     * Shares the search rate limit (300/minute per app), and shows the same
+     * `index_warming` / `index_building` as search while a corpus loads.
+     */
+    passages(options?: {
+        filter?: SearchFilter;
+        cursor?: string | null;
+        limit?: number;
+    }): Promise<DataSourcePassagePage>;
+    /**
+     * Every passage matching a filter, a page at a time behind the scenes: the
+     * walk over {@link passages}. Each page counts against the search rate
+     * limit, so a large walk belongs in a background task.
+     *
+     * ```ts
+     * for await (const passage of Manuals.allPassages({ entities: ['P-1004A'] })) {
+     *   mentions.push({ asset: 'P-1004A', ...passage.citation });
+     * }
+     * ```
+     */
+    allPassages(filter?: SearchFilter, options?: {
+        /** Passages per page, at most 200 (the default). */
+        pageSize?: number;
+    }): AsyncGenerator<DataSourcePassage, void, undefined>;
     /**
      * Every document in the corpus, oldest first, a page at a time behind the
      * scenes. This is how an app builds its own view of a large corpus (a
@@ -11816,7 +11869,12 @@ declare function defineMapper(source: {
  *   what named the document.
  * - `cleared(sourceId)` — the whole source was deleted, once, so the app can
  *   drop that source's rows in one statement. Optional.
- * A throw fails that delivery; the platform retries it.
+ * - `relinked(document)` — a document already read was re-tagged by a new
+ *   dictionary: its passages carry different entities, its text is the same.
+ *   For rows derived from the tags. Optional.
+ * A throw fails that delivery; the platform retries it. `document.bytes()`
+ * reads the file the document came from, for a reader that needs the drawing
+ * itself rather than its text.
  *
  * A reader runs against the app's LIVE release (or the dev session under
  * `reader test --dev`), never a pinned one: app databases are per release, so
@@ -11844,26 +11902,47 @@ interface ReaderDocument {
     pageCount: number | null;
     chunkCount: number | null;
     createdAt: string;
+    /**
+     * A short-lived link to the file the document came from: the uploaded
+     * file, or on a mapped source the raw object the mapper read. Valid for the
+     * delivery; null when the file is no longer kept.
+     */
+    url: string | null;
     /**
      * The document's passages as indexed: text, page, heading path, and each
      * passage's entities (its document's asserted ones and those its text
      * names from the source's dictionary). Read once, then held.
      */
     chunks(): Promise<DataSourceChunk[]>;
+    /** The bytes behind {@link url}: a drawing's image, a PDF's pages. Read once, then held. */
+    bytes(): Promise<Uint8Array>;
 }
 type MaybePromise<T> = T | Promise<T>;
 interface ReaderConfig {
     read: (document: ReaderDocument) => MaybePromise<void>;
     removed: (documentId: string) => MaybePromise<void>;
     cleared?: (sourceId: string) => MaybePromise<void>;
+    /**
+     * A document already read was re-tagged: the source's dictionary changed,
+     * and its passages' entities with it. The document arrives as `read` gets
+     * it, chunks and all, carrying the new entities, so rows derived from the
+     * tags (links from assets to documents) can follow. Nothing about the text
+     * changed, so this is no reason to extract again. Optional: without it a
+     * relink delivers nothing.
+     */
+    relinked?: (document: ReaderDocument) => MaybePromise<void>;
 }
-/** One delivery as the platform hands it to the executor. */
-type ReadDelivery = {
-    kind: 'read';
-    document: Omit<ReaderDocument, 'chunks'>;
+type DocumentDelivery = {
+    document: Omit<ReaderDocument, 'chunks' | 'bytes'>;
     /** The passages, when the platform carried them inline. */
     chunks?: DataSourceChunk[];
-} | {
+};
+/** One delivery as the platform hands it to the executor. */
+type ReadDelivery = ({
+    kind: 'read';
+} & DocumentDelivery) | ({
+    kind: 'relinked';
+} & DocumentDelivery) | {
     kind: 'removed';
     documentId: string;
 } | {
@@ -11894,6 +11973,10 @@ interface ReadRunRecord {
     v: 1;
     source: string;
     outcomes: ReadRunResult[];
+    /** The optional hooks this reader defines, so the platform sends only what one handles. */
+    hooks: {
+        relinked: boolean;
+    };
     startedAt: number;
     durationMs: number;
 }

package/dist/index.js

@@ -3261,7 +3261,8 @@ var DataSource = class {
    * it is who or what was written about then. No filter covers the corpus.
    * `chunks` is how many matching passages carry each id, not documents: a
    * long document's passages each count. Approximate counts, ordered most
-   * first; `limit` defaults to 20, at most 100.
+   * first; `limit` defaults to 20, at most 1,000. One document's entities:
+   * `{ filter: { documentIds: [id] } }`.
    *
    * Shares the search rate limit (300/minute per app), and shows the same
    * `index_warming` / `index_building` as search while a corpus loads.
@@ -3452,6 +3453,59 @@ var DataSource = class {
     });
     return { documents: documents2 ?? [], nextCursor: nextCursor ?? null };
   }
+  /**
+   * One page of the passages matching a filter, unranked: every page that
+   * mentions an asset (`{ entities: ['P-1004A'] }`), every passage holding a
+   * phrase, every chunk of some documents. Where {@link search} ranks and
+   * stops at its top results and {@link count} gives a number, this lists
+   * them all. Passages come document by document, each document's in order;
+   * pass `nextCursor` back for the next page, which is null after the last.
+   * `limit` defaults to 50, at most 200.
+   *
+   * Shares the search rate limit (300/minute per app), and shows the same
+   * `index_warming` / `index_building` as search while a corpus loads.
+   */
+  async passages(options) {
+    const { passages, nextCursor, latencyMs } = await this._call("passages", {
+      slug: this._slug,
+      ...options?.filter !== void 0 ? { filter: options.filter } : {},
+      ...options?.cursor ? { cursor: options.cursor } : {},
+      ...options?.limit !== void 0 ? { limit: options.limit } : {}
+    });
+    return {
+      passages: passages ?? [],
+      nextCursor: nextCursor ?? null,
+      latencyMs: latencyMs ?? 0
+    };
+  }
+  /**
+   * Every passage matching a filter, a page at a time behind the scenes: the
+   * walk over {@link passages}. Each page counts against the search rate
+   * limit, so a large walk belongs in a background task.
+   *
+   * ```ts
+   * for await (const passage of Manuals.allPassages({ entities: ['P-1004A'] })) {
+   *   mentions.push({ asset: 'P-1004A', ...passage.citation });
+   * }
+   * ```
+   */
+  async *allPassages(filter, options) {
+    let cursor = null;
+    while (true) {
+      const page = await this.passages({
+        ...filter !== void 0 ? { filter } : {},
+        cursor,
+        limit: options?.pageSize ?? 200
+      });
+      for (const passage of page.passages) {
+        yield passage;
+      }
+      if (!page.nextCursor || page.passages.length === 0) {
+        return;
+      }
+      cursor = page.nextCursor;
+    }
+  }
   /**
    * Every document in the corpus, oldest first, a page at a time behind the
    * scenes. This is how an app builds its own view of a large corpus (a
@@ -8519,6 +8573,7 @@ function errorInfo3(e) {
 function refOf(delivery) {
   switch (delivery.kind) {
     case "read":
+    case "relinked":
       return delivery.document.id;
     case "removed":
       return delivery.documentId;
@@ -8549,6 +8604,8 @@ async function withTimeout2(work, timeoutMs, ref) {
 function defineReader(source, config) {
   const documentFor = (delivery) => {
     let cached = delivery.chunks ? Promise.resolve(delivery.chunks) : null;
+    let bytes = null;
+    const { url } = delivery.document;
     return {
       ...delivery.document,
       chunks: () => {
@@ -8556,6 +8613,25 @@ function defineReader(source, config) {
           cached = source.chunks(delivery.document.id);
         }
         return cached;
+      },
+      bytes: () => {
+        if (!bytes) {
+          bytes = (async () => {
+            if (!url) {
+              throw new Error(
+                `The file behind document ${delivery.document.id} is no longer kept.`
+              );
+            }
+            const response = await fetch(url);
+            if (!response.ok) {
+              throw new Error(
+                `Could not read the file behind document ${delivery.document.id}: HTTP ${response.status}`
+              );
+            }
+            return new Uint8Array(await response.arrayBuffer());
+          })();
+        }
+        return bytes;
       }
     };
   };
@@ -8564,6 +8640,9 @@ function defineReader(source, config) {
       case "read":
         await config.read(documentFor(delivery));
         return;
+      case "relinked":
+        await config.relinked?.(documentFor(delivery));
+        return;
       case "removed":
         await config.removed(delivery.documentId);
         return;
@@ -8618,6 +8697,7 @@ function defineReader(source, config) {
       v: 1,
       source: source.name,
       outcomes,
+      hooks: { relinked: typeof config.relinked === "function" },
       startedAt,
       durationMs: Date.now() - startedAt
     };