@inflexa-ai/harness 0.48.3 → 0.48.5

package/dist/tools/lib/humanbase-client.js

@@ -0,0 +1,187 @@
+/**
+ * Pure async client functions for HumanBase (Flatiron Institute), which serves
+ * the GIANT functional networks: one network for each tissue, cell type, or
+ * biological-process context (Greene et al., Nature Genetics 2015).
+ *
+ * Absence policy: HumanBase keeps the key of an absent value and sends an
+ * explicit `null` — `mincut` of a v3 network, and `term` and `version` of a
+ * context. Thus a maybe-absent field carries `.nullable()`, not `.optional()`.
+ *
+ * HumanBase asks for no key and no caller identity. The shared
+ * `HARNESS_USER_AGENT` of `apiFetch` names the caller.
+ *
+ * The GIANT version is a property of the slug: each v3 slug ends in `-v3`, and
+ * no v1 slug does. The network endpoint refuses a `giant_version` that disagrees
+ * with the slug (a 400 for a v3 slug under v1, a 404 for a v1 slug under v3),
+ * thus the client derives the version from the slug and no caller states it.
+ *
+ * Only an HTTP 404 is an expected absence (an unknown slug, or no queried gene in
+ * the network). A 400 carries the message of a refused request, thus it is not
+ * read as "nothing there" — `isUnexpectedApiError` would read every 4xx that way.
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError } from "./api-utils.js";
+const HUMANBASE_BASE = "https://hb.flatironinstitute.org/api/integrations";
+/** The network endpoint refuses a larger query gene set with a 400. */
+export const HUMANBASE_MAX_NETWORK_GENES = 30;
+const V3_SLUG_SUFFIX = "-v3";
+/** The GIANT version of a context slug. */
+export function giantVersionOf(slug) {
+    return slug.endsWith(V3_SLUG_SUFFIX) ? "v3" : "v1";
+}
+const ContextSchema = z.object({
+    title: z.string(),
+    term: z
+        .object({
+        identifier: z.string(),
+        database: z.object({ name: z.string() }),
+    })
+        .nullable(),
+    version: z.object({ identifier: z.string() }).nullable(),
+});
+function toContext(slug, context) {
+    return {
+        slug,
+        title: context.title,
+        giantVersion: giantVersionOf(slug),
+        term: context.term === null ? null : { id: context.term.identifier, ontology: context.term.database.name },
+    };
+}
+/** One row of `GET /api/integrations/`. */
+export const HumanBaseIntegrationSchema = z
+    .object({
+    slug: z.string(),
+    context: ContextSchema,
+})
+    .transform((d) => toContext(d.slug, d.context));
+/** One row of `POST /api/integrations/relevant/`. */
+export const HumanBaseRelevantSchema = z
+    .object({
+    slug: z.string(),
+    context: ContextSchema,
+    score: z.number(),
+})
+    .transform((d) => ({ ...toContext(d.slug, d.context), score: d.score }));
+const XrefSchema = z.object({
+    xrid: z.string(),
+    crossrefdb: z.object({ name: z.string() }),
+});
+const NetworkGeneSchema = z.object({
+    entrez: z.number().int(),
+    standard_name: z.string(),
+    description: z.string(),
+    xrefs: z.array(XrefSchema),
+    query: z.boolean(),
+});
+/** An edge names its two genes by their index in `genes`, not by an Entrez ID. */
+const NetworkEdgeSchema = z.object({
+    source: z.number().int().nonnegative(),
+    target: z.number().int().nonnegative(),
+    weight: z.number(),
+});
+function xrefOf(xrefs, database) {
+    return xrefs.find((xref) => xref.crossrefdb.name === database)?.xrid ?? null;
+}
+/** The body of `GET /api/integrations/{slug}/network/`, with each edge resolved to the symbols of its genes. */
+export const HumanBaseNetworkSchema = z
+    .object({
+    mincut: z.number().nullable(),
+    genes: z.array(NetworkGeneSchema),
+    edges: z.array(NetworkEdgeSchema),
+})
+    .superRefine((d, ctx) => {
+    for (const [index, edge] of d.edges.entries()) {
+        if (edge.source >= d.genes.length || edge.target >= d.genes.length) {
+            ctx.addIssue({ code: "custom", path: ["edges", index], message: "an edge names a gene index outside genes" });
+        }
+    }
+})
+    .transform((d) => {
+    const genes = d.genes.map((gene) => ({
+        entrez: gene.entrez,
+        symbol: gene.standard_name,
+        description: gene.description,
+        ensembl: xrefOf(gene.xrefs, "Ensembl"),
+        hgnc: xrefOf(gene.xrefs, "HGNC"),
+        query: gene.query,
+    }));
+    const symbolAt = (index) => genes[index]?.symbol ?? "";
+    const edges = d.edges.map((edge) => ({ geneA: symbolAt(edge.source), geneB: symbolAt(edge.target), weight: edge.weight }));
+    return { mincut: d.mincut, genes, edges };
+});
+function isNotFound(error) {
+    return error.type === "http_status" && error.status === 404;
+}
+/**
+ * Each context that HumanBase serves, filtered by a case-insensitive substring of
+ * the slug or the title. The list holds about 600 rows, thus `limit` trims it and
+ * `totalFound` reports the count of the filtered list.
+ */
+export async function listContexts(options = {}) {
+    const res = await apiFetchValidated(`${HUMANBASE_BASE}/`, z.array(HumanBaseIntegrationSchema));
+    if (res.isErr())
+        throw new Error(describeApiError(res.error));
+    const needle = options.query?.trim().toLowerCase() ?? "";
+    const matched = needle === "" ? res.value : res.value.filter((c) => c.slug.toLowerCase().includes(needle) || c.title.toLowerCase().includes(needle));
+    const limit = options.limit ?? matched.length;
+    return { contexts: matched.slice(0, limit), totalFound: matched.length };
+}
+/**
+ * The contexts ranked by their relevance to a gene set, best first.
+ *
+ * HumanBase ranks the v1 contexts only, and it gives an empty list when it knows
+ * none of the genes. The endpoint takes each Entrez ID as a JSON string and
+ * answers a JSON number with a 500.
+ */
+export async function getRelevantContexts(entrez, options = {}) {
+    const res = await apiFetchValidated(`${HUMANBASE_BASE}/relevant/`, z.array(HumanBaseRelevantSchema), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ entrez: entrez.map(String) }),
+    });
+    if (res.isErr()) {
+        // The published schema of the endpoint documents a 404 for an unknown gene.
+        if (isNotFound(res.error))
+            return { contexts: [], totalFound: 0 };
+        throw new Error(describeApiError(res.error));
+    }
+    const sorted = res.value.sort((a, b) => b.score - a.score);
+    const limit = options.limit ?? sorted.length;
+    return { contexts: sorted.slice(0, limit), totalFound: sorted.length };
+}
+/**
+ * The functional subnetwork of the query genes in one context, plus `nodeSize`
+ * neighbor genes that HumanBase adds. The answer holds an edge for each gene
+ * pair, thus the edge count grows with the square of the gene count: `limit`
+ * trims the weight-sorted edges, and `totalEdges` reports the true count.
+ *
+ * Gives `null` on an HTTP 404: the slug is unknown, or no query gene is in the
+ * network.
+ */
+export async function getNetwork(slug, entrez, options = {}) {
+    const giantVersion = giantVersionOf(slug);
+    const params = new URLSearchParams();
+    for (const id of entrez)
+        params.append("entrez", String(id));
+    if (options.nodeSize !== undefined)
+        params.set("node_size", String(options.nodeSize));
+    params.set("giant_version", giantVersion);
+    const res = await apiFetchValidated(`${HUMANBASE_BASE}/${encodeURIComponent(slug)}/network/?${params}`, HumanBaseNetworkSchema);
+    if (res.isErr()) {
+        if (isNotFound(res.error))
+            return null;
+        throw new Error(describeApiError(res.error));
+    }
+    const returned = new Set(res.value.genes.map((gene) => gene.entrez));
+    const edges = res.value.edges.sort((a, b) => b.weight - a.weight);
+    const limit = options.limit ?? edges.length;
+    return {
+        context: slug,
+        giantVersion,
+        mincut: res.value.mincut,
+        genes: res.value.genes,
+        edges: edges.slice(0, limit),
+        totalEdges: edges.length,
+        notFound: entrez.filter((id) => !returned.has(id)),
+    };
+}

package/dist/tools/lib/mygene-client.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Pure async client functions for MyGene.info (BioThings, Scripps), which maps a
+ * gene across the identifier spaces of its sources: the HGNC symbol, the NCBI
+ * Entrez Gene ID, the Ensembl gene ID, and the UniProt accession (Xin et al.,
+ * Genome Biology 2016).
+ *
+ * Absence policy: MyGene omits the key of an absent value and never sends an
+ * explicit `null`. Every field of a hit can be absent — an Ensembl-only gene has
+ * no `symbol`, `name`, or `entrezgene`, and a noncoding gene has no `uniprot` —
+ * thus each field carries `.optional()`.
+ *
+ * Two fields change their shape with their count: `ensembl` is one object or an
+ * array of objects (a gene on alternate haplotypes, or a mouse gene with strain
+ * copies), and `uniprot.Swiss-Prot` is one string or an array. The client
+ * normalizes both to an array, in the wire order, which carries no rank.
+ *
+ * A miss is no error: the batch answers HTTP 200, and it marks the miss with
+ * `notfound: true`.
+ *
+ * MyGene cuts the hits of each identifier at `size`, 10 by default, and the plain
+ * batch answer gives no sign of the cut. Thus the client sends `size` and
+ * `with_total`, and the answer is then an object: `max_total`, the largest hit
+ * count of one identifier before the cut, and `hits`, the rows. An unknown species answers HTTP 400 with a message, which the
+ * caller sees as an error.
+ */
+import { z } from "zod";
+/** The most hits that one identifier gives. A UniProt accession that a gene family shares gives a hit for each member. */
+export declare const MYGENE_HITS_PER_ID = 100;
+export type MyGeneHit = {
+    /** The identifier of the request that this hit answers. */
+    query: string;
+    symbol: string | null;
+    /** The full name of the gene. */
+    name: string | null;
+    entrez: number | null;
+    ensembl: string[];
+    /** The reviewed (Swiss-Prot) UniProt accessions. */
+    uniprot: string[];
+};
+export type MyGeneRow = {
+    kind: "hit";
+    hit: MyGeneHit;
+} | {
+    kind: "miss";
+    query: string;
+};
+export type GeneIdResolution = {
+    genes: MyGeneHit[];
+    /** Each identifier that matched no gene. */
+    notFound: string[];
+    /** Each identifier that matched more than one gene. Each of its genes is in `genes`. */
+    ambiguous: string[];
+    /** Each identifier whose hits were cut at `MYGENE_HITS_PER_ID`. `genes` holds the first of them only. */
+    truncated: string[];
+};
+/** One row of the batch answer of `POST /v3/query`: a hit, or the miss of one query. */
+export declare const MyGeneBatchRowSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodObject<{
+    query: z.ZodString;
+    notfound: z.ZodLiteral<true>;
+}, z.core.$strip>, z.ZodObject<{
+    query: z.ZodString;
+    _id: z.ZodString;
+    symbol: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    entrezgene: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>;
+    ensembl: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        gene: z.ZodString;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+        gene: z.ZodString;
+    }, z.core.$strip>>]>>;
+    uniprot: z.ZodOptional<z.ZodObject<{
+        "Swiss-Prot": z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>]>, z.ZodTransform<{
+    kind: "hit";
+    hit: MyGeneHit;
+} | {
+    kind: "miss";
+    query: string;
+}, {
+    query: string;
+    notfound: true;
+} | {
+    query: string;
+    _id: string;
+    symbol?: string | undefined;
+    name?: string | undefined;
+    entrezgene?: number | null | undefined;
+    ensembl?: {
+        gene: string;
+    }[] | {
+        gene: string;
+    } | undefined;
+    uniprot?: {
+        "Swiss-Prot"?: string | string[] | undefined;
+    } | undefined;
+}>>;
+/** The batch answer of `POST /v3/query` with `with_total`. */
+export declare const MyGeneBatchAnswerSchema: z.ZodObject<{
+    max_total: z.ZodNumber;
+    hits: z.ZodArray<z.ZodPipe<z.ZodUnion<readonly [z.ZodObject<{
+        query: z.ZodString;
+        notfound: z.ZodLiteral<true>;
+    }, z.core.$strip>, z.ZodObject<{
+        query: z.ZodString;
+        _id: z.ZodString;
+        symbol: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        entrezgene: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>;
+        ensembl: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            gene: z.ZodString;
+        }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+            gene: z.ZodString;
+        }, z.core.$strip>>]>>;
+        uniprot: z.ZodOptional<z.ZodObject<{
+            "Swiss-Prot": z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>, z.ZodTransform<{
+        kind: "hit";
+        hit: MyGeneHit;
+    } | {
+        kind: "miss";
+        query: string;
+    }, {
+        query: string;
+        notfound: true;
+    } | {
+        query: string;
+        _id: string;
+        symbol?: string | undefined;
+        name?: string | undefined;
+        entrezgene?: number | null | undefined;
+        ensembl?: {
+            gene: string;
+        }[] | {
+            gene: string;
+        } | undefined;
+        uniprot?: {
+            "Swiss-Prot"?: string | string[] | undefined;
+        } | undefined;
+    }>>>;
+}, z.core.$strip>;
+/**
+ * Resolve a batch of gene identifiers, mixed freely, in one request. A duplicate
+ * identifier is sent one time, and the order of the input is kept.
+ *
+ * `species` is a common name that MyGene knows ('human', 'mouse', 'rat',
+ * 'zebrafish', …) or an NCBI Taxonomy ID as a string ('9606').
+ */
+export declare function resolveGeneIds(identifiers: readonly string[], species: string): Promise<GeneIdResolution>;

package/dist/tools/lib/mygene-client.js

@@ -0,0 +1,109 @@
+/**
+ * Pure async client functions for MyGene.info (BioThings, Scripps), which maps a
+ * gene across the identifier spaces of its sources: the HGNC symbol, the NCBI
+ * Entrez Gene ID, the Ensembl gene ID, and the UniProt accession (Xin et al.,
+ * Genome Biology 2016).
+ *
+ * Absence policy: MyGene omits the key of an absent value and never sends an
+ * explicit `null`. Every field of a hit can be absent — an Ensembl-only gene has
+ * no `symbol`, `name`, or `entrezgene`, and a noncoding gene has no `uniprot` —
+ * thus each field carries `.optional()`.
+ *
+ * Two fields change their shape with their count: `ensembl` is one object or an
+ * array of objects (a gene on alternate haplotypes, or a mouse gene with strain
+ * copies), and `uniprot.Swiss-Prot` is one string or an array. The client
+ * normalizes both to an array, in the wire order, which carries no rank.
+ *
+ * A miss is no error: the batch answers HTTP 200, and it marks the miss with
+ * `notfound: true`.
+ *
+ * MyGene cuts the hits of each identifier at `size`, 10 by default, and the plain
+ * batch answer gives no sign of the cut. Thus the client sends `size` and
+ * `with_total`, and the answer is then an object: `max_total`, the largest hit
+ * count of one identifier before the cut, and `hits`, the rows. An unknown species answers HTTP 400 with a message, which the
+ * caller sees as an error.
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError, zWireNumber } from "./api-utils.js";
+const MYGENE_QUERY_URL = "https://mygene.info/v3/query";
+/**
+ * The identifier spaces that a query matches. `alias` is not one of them: an old
+ * or informal symbol matches several current genes with an equal score, and no
+ * rule picks one.
+ */
+const SCOPES = "symbol,entrezgene,ensembl.gene,uniprot";
+const FIELDS = "symbol,name,entrezgene,ensembl.gene,uniprot.Swiss-Prot";
+/** The most hits that one identifier gives. A UniProt accession that a gene family shares gives a hit for each member. */
+export const MYGENE_HITS_PER_ID = 100;
+function asArray(value) {
+    if (value === undefined)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+const EnsemblRefSchema = z.object({ gene: z.string() });
+const MissRowSchema = z.object({ query: z.string(), notfound: z.literal(true) });
+const HitRowSchema = z.object({
+    query: z.string(),
+    _id: z.string(),
+    symbol: z.string().optional(),
+    name: z.string().optional(),
+    entrezgene: zWireNumber.optional(),
+    ensembl: z.union([EnsemblRefSchema, z.array(EnsemblRefSchema)]).optional(),
+    uniprot: z.object({ "Swiss-Prot": z.union([z.string(), z.array(z.string())]).optional() }).optional(),
+});
+/** One row of the batch answer of `POST /v3/query`: a hit, or the miss of one query. */
+export const MyGeneBatchRowSchema = z.union([MissRowSchema, HitRowSchema]).transform((row) => {
+    if ("notfound" in row)
+        return { kind: "miss", query: row.query };
+    return {
+        kind: "hit",
+        hit: {
+            query: row.query,
+            symbol: row.symbol ?? null,
+            name: row.name ?? null,
+            entrez: row.entrezgene ?? null,
+            ensembl: asArray(row.ensembl).map((ref) => ref.gene),
+            uniprot: asArray(row.uniprot?.["Swiss-Prot"]),
+        },
+    };
+});
+/** The batch answer of `POST /v3/query` with `with_total`. */
+export const MyGeneBatchAnswerSchema = z.object({
+    max_total: z.number(),
+    hits: z.array(MyGeneBatchRowSchema),
+});
+/**
+ * Resolve a batch of gene identifiers, mixed freely, in one request. A duplicate
+ * identifier is sent one time, and the order of the input is kept.
+ *
+ * `species` is a common name that MyGene knows ('human', 'mouse', 'rat',
+ * 'zebrafish', …) or an NCBI Taxonomy ID as a string ('9606').
+ */
+export async function resolveGeneIds(identifiers, species) {
+    const queries = [...new Set(identifiers.map((id) => id.trim()).filter((id) => id !== ""))];
+    if (queries.length === 0)
+        return { genes: [], notFound: [], ambiguous: [], truncated: [] };
+    const res = await apiFetchValidated(MYGENE_QUERY_URL, MyGeneBatchAnswerSchema, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ q: queries, scopes: SCOPES, fields: FIELDS, species, size: MYGENE_HITS_PER_ID, with_total: true }),
+    });
+    if (res.isErr())
+        throw new Error(describeApiError(res.error));
+    const genes = [];
+    const notFound = [];
+    const hitCount = new Map();
+    for (const row of res.value.hits) {
+        if (row.kind === "miss") {
+            notFound.push(row.query);
+            continue;
+        }
+        genes.push(row.hit);
+        hitCount.set(row.hit.query, (hitCount.get(row.hit.query) ?? 0) + 1);
+    }
+    const ambiguous = [...hitCount].filter(([, count]) => count > 1).map(([query]) => query);
+    // `max_total` is one number for the whole batch. Past the cap, each identifier that filled the cap can be the one
+    // that was cut, thus each such identifier counts as cut.
+    const truncated = res.value.max_total > MYGENE_HITS_PER_ID ? [...hitCount].filter(([, count]) => count >= MYGENE_HITS_PER_ID).map(([query]) => query) : [];
+    return { genes, notFound, ambiguous, truncated };
+}

package/dist/tools/lib/opentargets-client.js

@@ -122,6 +122,10 @@ const BASELINE_EXPRESSION_PAGE_SIZE = 3000;
 // that resolves empty — an unknown/retired id yields `{"target": null}`, which a
 // bare `.optional()` rejects, turning a clean "not found" into a thrown error.
 const DatatypeScoreSchema = z.object({ id: z.string().optional(), score: z.number().optional() });
+/** The datatype-scores list follows the same nullable-optional reading rule as its row, and may be absent or null. */
+const scoresField = z.array(DatatypeScoreSchema).nullable().optional();
+/** The paged rows list of an association query: the API may omit or null the whole envelope. */
+const rowsEnvelope = (item) => z.object({ rows: z.array(item).nullable().optional() });
 export const TargetAssociationsDataSchema = z.object({
     target: z
         .object({
@@ -137,18 +141,11 @@ export const TargetAssociationsDataSchema = z.object({
         .optional(),
     associations: z
         .object({
-        associatedDiseases: z
-            .object({
-            rows: z
-                .array(z.object({
-                disease: z.object({ id: z.string(), name: z.string() }),
-                score: z.number(),
-                datatypeScores: z.array(DatatypeScoreSchema).nullable().optional(),
-            }))
-                .nullable()
-                .optional(),
-        })
-            .optional(),
+        associatedDiseases: rowsEnvelope(z.object({
+            disease: z.object({ id: z.string(), name: z.string() }),
+            score: z.number(),
+            datatypeScores: scoresField,
+        })).optional(),
     })
         .nullable()
         .optional(),
@@ -158,21 +155,14 @@ const DiseaseAssociationsDataSchema = z.object({
         .object({
         id: z.string().optional(),
         name: z.string().optional(),
-        associatedTargets: z
-            .object({
-            rows: z
-                .array(z.object({
-                target: z
-                    .object({ id: z.string().optional(), approvedSymbol: z.string().optional(), approvedName: z.string().optional() })
-                    .nullable()
-                    .optional(),
-                score: z.number(),
-                datatypeScores: z.array(DatatypeScoreSchema).nullable().optional(),
-            }))
+        associatedTargets: rowsEnvelope(z.object({
+            target: z
+                .object({ id: z.string().optional(), approvedSymbol: z.string().optional(), approvedName: z.string().optional() })
                 .nullable()
                 .optional(),
-        })
-            .optional(),
+            score: z.number(),
+            datatypeScores: scoresField,
+        })).optional(),
     })
         .nullable()
         .optional(),

package/dist/tools/report-authoring/authoring-tools.d.ts

@@ -34,9 +34,8 @@ import type { DraftDocument } from "../../report-model/draft.js";
 import type { ReportSnapshot } from "../../report-model/reference-resolver.js";
 import type { DerivationRecord } from "../../state/report-session-state.js";
 import { type Tool } from "../define-tool.js";
-/** The flat destination fields. An anchor is `before` or `after`, and a place is `start` or `end`. */
+/** The flat destination fields of the add, plus the payload of the new block. */
 declare const addBlockInput: z.ZodObject<{
-    block: z.ZodUnion<readonly [z.ZodType<import("../../report-model/authoring-grammar.js").AuthoringBlock, unknown, z.core.$ZodTypeInternals<import("../../report-model/authoring-grammar.js").AuthoringBlock, unknown>>, z.ZodUnknown]>;
     parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     place: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
         end: "end";
@@ -44,6 +43,7 @@ declare const addBlockInput: z.ZodObject<{
     }>>>;
     before: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     after: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    block: z.ZodUnion<readonly [z.ZodType<import("../../report-model/authoring-grammar.js").AuthoringBlock, unknown, z.core.$ZodTypeInternals<import("../../report-model/authoring-grammar.js").AuthoringBlock, unknown>>, z.ZodUnknown]>;
 }, z.core.$strip>;
 /**
  * The change payload is a title for a section target, or a block for an atom target, and exactly one of
@@ -59,7 +59,6 @@ declare const removeBlockInput: z.ZodObject<{
     targetId: z.ZodString;
 }, z.core.$strip>;
 declare const moveBlockInput: z.ZodObject<{
-    targetId: z.ZodString;
     parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     place: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
         end: "end";
@@ -67,6 +66,7 @@ declare const moveBlockInput: z.ZodObject<{
     }>>>;
     before: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     after: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    targetId: z.ZodString;
 }, z.core.$strip>;
 declare const readOutlineInput: z.ZodObject<{}, z.core.$strip>;
 /** The read names its target with the same field name as each mutation, thus one id key serves them all. */

package/dist/tools/report-authoring/authoring-tools.js

@@ -70,12 +70,16 @@ const DESTINATION_NOTES = {
     after: "The id of a sibling block. The block lands directly after it.",
 };
 /** The flat destination fields. An anchor is `before` or `after`, and a place is `start` or `end`. */
-const addBlockInput = z.object({
-    block: blockPayload,
+const destinationFields = {
     parentId: absentable(z.string()).describe(DESTINATION_NOTES.parentId),
     place: absentable(z.enum(["start", "end"])).describe(DESTINATION_NOTES.place),
     before: absentable(z.string()).describe(DESTINATION_NOTES.before),
     after: absentable(z.string()).describe(DESTINATION_NOTES.after),
+};
+/** The flat destination fields of the add, plus the payload of the new block. */
+const addBlockInput = z.object({
+    block: blockPayload,
+    ...destinationFields,
 });
 /**
  * The change payload is a title for a section target, or a block for an atom target, and exactly one of
@@ -92,10 +96,7 @@ const removeBlockInput = z.object({
 });
 const moveBlockInput = z.object({
     targetId: z.string().describe("The id of the block to move, as the outline gives it."),
-    parentId: absentable(z.string()).describe(DESTINATION_NOTES.parentId),
-    place: absentable(z.enum(["start", "end"])).describe(DESTINATION_NOTES.place),
-    before: absentable(z.string()).describe(DESTINATION_NOTES.before),
-    after: absentable(z.string()).describe(DESTINATION_NOTES.after),
+    ...destinationFields,
 });
 const readOutlineInput = z.object({});
 /** The read names its target with the same field name as each mutation, thus one id key serves them all. */

package/dist/tools/research/generate-analogy-report.js

@@ -260,7 +260,9 @@ export function createGenerateAnalogyReportTool(deps, registerSubAgent) {
             "drives a multi-step research sub-agent (up to 40 model turns) over live " +
             "literature search, so it is slow; a fact that one lookup answers does " +
             "not need it.\n" +
-            "RETURNS an AnalogyReport envelope the UI renders as an inline card. An " +
+            "RETURNS an AnalogyReport envelope. The analogy block shows the full " +
+            "report to the user, thus your reply names the analogies that matter by " +
+            "their `analogyTitle` and does not copy the report. An " +
             "analogy the search could not fill carries a `coverage` tag " +
             "(`queried_no_data` | `search_failed` | `not_loaded`) with an empty " +
             "`solutions` array — a partial result, not an error. A top-level `error` " +
@@ -273,7 +275,13 @@ export function createGenerateAnalogyReportTool(deps, registerSubAgent) {
         view: "none",
         describeCall: "none",
         startsWorkflow: true,
-        execute: async (input, ctx) => ok(await research(input, ctx)),
+        execute: async (input, ctx) => {
+            const report = await research(input, ctx);
+            // The execute runs in the body of the turn, where a stream write is checkpointed, thus a replay gives no second
+            // part. The root session keeps the part in the stored display, which drops each frame of a sub-agent.
+            await ctx.emit({ type: "data-analogy-report", source: ctx.session.provenance, data: { id: ctx.invocationId, report } });
+            return ok(report);
+        },
     });
 }
 /** The envelope of a run that recorded no outcome, also after its salvage. */