@inflexa-ai/harness 0.30.3 → 0.31.0

package/dist/tools/lib/pubchem-ops.js

@@ -4,14 +4,20 @@
  * One home for the wire schemas, the URL construction, and the "PubChem 404
  * means no data" contract, so a caller cannot drift from it: every function
  * returns an empty collection for a 404 and throws on any other API failure.
+ *
+ * Absence policy: PubChem omits the key of an absent value, per `minOccurs=0`
+ * in its XSD, and it never sends an explicit `null`. Thus a maybe-absent field
+ * carries `.optional()`, not `.nullable()`.
  */
 import { z } from "zod";
-import { apiFetchValidated, describeApiError } from "./api-utils.js";
+import { apiFetchValidated, describeApiError, parseWireNumber, zWireNumber } from "./api-utils.js";
 import { PUBCHEM_HEADERS as HEADERS, PUBCHEM_BASE } from "./pubchem-config.js";
 const PROPERTY_LIST = [
     "MolecularFormula",
     "MolecularWeight",
-    "CanonicalSMILES",
+    // PubChem retired the response key `CanonicalSMILES`, and it answers a request
+    // for that name with `ConnectivitySMILES`. Thus the request names the live key.
+    "ConnectivitySMILES",
     "InChI",
     "InChIKey",
     "IUPACName",
@@ -31,12 +37,11 @@ const PROPERTY_LIST = [
 const PugPropertyRowSchema = z
     .object({
     CID: z.number().optional(),
-    CanonicalSMILES: z.string().optional(),
+    ConnectivitySMILES: z.string().optional(),
     MolecularFormula: z.string().optional(),
     // PUG-REST serializes MolecularWeight as a string (e.g. "180.16") to
-    // preserve significant figures; accept both and let the transform's
-    // `Number(...)` normalize it.
-    MolecularWeight: z.union([z.number(), z.string()]).optional(),
+    // preserve significant figures, thus it reads through the wire-number helper.
+    MolecularWeight: zWireNumber.optional(),
     IUPACName: z.string().optional(),
     InChI: z.string().optional(),
     InChIKey: z.string().optional(),
@@ -49,9 +54,9 @@ const PugPropertyRowSchema = z
 })
     .transform((raw) => ({
     cid: raw.CID ?? 0,
-    canonicalSmiles: raw.CanonicalSMILES ?? null,
+    canonicalSmiles: raw.ConnectivitySMILES ?? null,
     molecularFormula: raw.MolecularFormula ?? null,
-    molecularWeight: raw.MolecularWeight != null ? Number(raw.MolecularWeight) : null,
+    molecularWeight: raw.MolecularWeight ?? null,
     iupacName: raw.IUPACName ?? null,
     inchi: raw.InChI ?? null,
     inchiKey: raw.InChIKey ?? null,
@@ -62,50 +67,77 @@ const PugPropertyRowSchema = z
     rotatableBondCount: raw.RotatableBondCount ?? null,
     complexity: raw.Complexity ?? null,
 }));
-const PubChemPropertyResponseSchema = z.object({
+export const PubChemPropertyResponseSchema = z.object({
     PropertyTable: z.object({ Properties: z.array(PugPropertyRowSchema).optional() }).optional(),
 });
 // The PUG-REST xrefs wire shape, validated at the fetch boundary: one
-// `Information` entry per CID with parallel `RegistryID[]` / `SourceName[]`
-// arrays. Every field is optional — PubChem omits absent values.
-const PubChemXrefResponseSchema = z.object({
+// `Information` entry per CID with its `RegistryID[]` list. Every field is
+// optional — PubChem omits absent values.
+export const PubChemXrefResponseSchema = z.object({
     InformationList: z
         .object({
         Information: z
             .array(z.object({
             CID: z.number().optional(),
             RegistryID: z.array(z.string()).optional(),
-            SourceName: z.array(z.string()).optional(),
         }))
             .optional(),
     })
         .optional(),
 });
-// The PUG-REST assay-summary wire shape (a table of columns + rows), validated
-// at the fetch boundary; `parseAssaySummary` maps the heading-indexed cells into
-// `PubChemAssay` records. Every field is optional — PubChem omits absent values.
-const PugAssaySummarySchema = z.object({
+/**
+ * The registry of each identifier pattern that PubChem serves in `RegistryID`.
+ *
+ * The `RegistryID` and `SourceName` lists of the endpoint are not parallel and
+ * they hold a different number of entries, thus an index cannot pair them. The
+ * identifier itself carries the registry, and the pattern reads it.
+ *
+ * A loose pattern runs last, thus a specific registry claims its own id first.
+ */
+const REGISTRY_PATTERNS = [
+    ["ChEMBL", /^CHEMBL\d+$/],
+    ["ChEBI", /^CHEBI:\d+$/],
+    ["DrugBank", /^DB\d{5}$/],
+    ["KEGG", /^[CD]\d{5}$/],
+    ["HMDB", /^HMDB\d+$/],
+    ["CAS", /^\d{2,7}-\d{2}-\d$/],
+    // A PDB id is four characters that start with a digit. The lookahead demands a
+    // letter as well, thus a plain registry number does not read as a structure.
+    ["PDB", /^[1-9](?=.*[A-Za-z])[0-9A-Za-z]{3}$/],
+    // A UNII is ten alphanumeric characters, and the lookahead demands a letter
+    // among them. A plain ten-digit registry number, such as `0000050782`, matches
+    // the pattern without it, and the row then names the wrong registry.
+    ["UNII", /^(?=.*[A-Z])[A-Z0-9]{10}$/],
+];
+/** The registry of one identifier, or `null` when no pattern matches it. */
+export function classifyRegistryId(id) {
+    for (const [source, pattern] of REGISTRY_PATTERNS) {
+        if (pattern.test(id))
+            return source;
+    }
+    return null;
+}
+// The PUG-REST assay-summary wire shape, validated at the fetch boundary: one
+// `Column` list of plain heading strings, and one `Cell` list of plain strings
+// for each row, with an entry for each column. An empty cell is the empty
+// string. `parseAssaySummary` maps the heading-indexed cells into `PubChemAssay`
+// records. Every field is optional — PubChem omits absent values.
+export const PugAssaySummarySchema = z.object({
     Table: z
         .object({
-        Columns: z
-            .object({
-            Column: z.array(z.object({ Heading: z.string().optional() })).optional(),
-        })
-            .optional(),
-        Row: z
-            .array(z.object({
-            Cell: z
-                .array(z.object({
-                intval: z.number().optional(),
-                fval: z.number().optional(),
-                sval: z.string().optional(),
-            }))
-                .optional(),
-        }))
-            .optional(),
+        Columns: z.object({ Column: z.array(z.string()).optional() }).optional(),
+        Row: z.array(z.object({ Cell: z.array(z.string()).optional() })).optional(),
     })
         .optional(),
 });
+/** The wire headings that the assay summary carries. They hold spaces and a unit. */
+const ASSAY_HEADINGS = {
+    aid: "AID",
+    assayName: "Assay Name",
+    targetAccession: "Target Accession",
+    activityOutcome: "Activity Outcome",
+    activityValue: "Activity Value [uM]",
+};
 /** Build the PUG-REST URL path segment for the given search type. */
 function buildNamespace(searchBy, query) {
     switch (searchBy) {
@@ -135,11 +167,21 @@ export async function fetchPubchemCompounds(query, searchBy) {
         throw new Error(describeApiError(res.error));
     }
     // Already validated + normalized by PugPropertyRowSchema's transform.
-    return res.value.PropertyTable?.Properties ?? [];
+    return (res.value.PropertyTable?.Properties ?? []).filter(carriesProperties);
+}
+/**
+ * Does the row hold a property?
+ *
+ * PubChem answers HTTP 200 for a CID that does not exist, with one row that
+ * carries the `CID` alone. Thus a row with no property is an absence, and a
+ * caller must not read it as a compound.
+ */
+function carriesProperties(row) {
+    return Object.entries(row).some(([key, value]) => key !== "cid" && value !== null);
 }
 /** External registry ids for a CID. Empty array = the CID is in no external registry. */
 export async function fetchPubchemCrossRefs(cid) {
-    const url = `${PUBCHEM_BASE}/compound/cid/${cid}/xrefs/RegistryID,SourceName/JSON`;
+    const url = `${PUBCHEM_BASE}/compound/cid/${cid}/xrefs/RegistryID/JSON`;
     const res = await apiFetchValidated(url, PubChemXrefResponseSchema, { headers: HEADERS });
     if (res.isErr()) {
         // PubChem returns 404 when the CID has no cross-references — expected.
@@ -148,20 +190,10 @@ export async function fetchPubchemCrossRefs(cid) {
         throw new Error(describeApiError(res.error));
     }
     // PUG-REST xrefs returns an InformationList with one entry per CID.
-    // Each entry has parallel RegistryID[] and SourceName[] arrays.
     const info = res.value.InformationList?.Information?.[0];
     if (!info?.RegistryID?.length)
         return [];
-    const crossRefs = [];
-    const registryIds = info.RegistryID;
-    const sourceNames = info.SourceName ?? [];
-    for (let i = 0; i < registryIds.length; i++) {
-        crossRefs.push({
-            source: sourceNames[i] ?? "Unknown",
-            id: registryIds[i] ?? "",
-        });
-    }
-    return crossRefs;
+    return info.RegistryID.map((id) => ({ source: classifyRegistryId(id), id }));
 }
 /** Bioassay screening summaries for a CID. Empty array = never screened. */
 export async function fetchPubchemAssays(cid, opts) {
@@ -179,39 +211,35 @@ export async function fetchPubchemAssays(cid, opts) {
     }
     return assays.slice(0, opts.limit);
 }
-function parseAssaySummary(data) {
+/**
+ * Read the assay table by its wire headings.
+ *
+ * The `targetName` of a record is the target accession, because the table names
+ * no protein. The accession resolves against UniProt or against a ChEMBL target.
+ */
+export function parseAssaySummary(data) {
     const columns = data.Table?.Columns?.Column ?? [];
     const rows = data.Table?.Row ?? [];
-    // Find column indices by heading
     const headingIndex = new Map();
-    for (let i = 0; i < columns.length; i++) {
-        if (columns[i].Heading) {
-            headingIndex.set(columns[i].Heading, i);
-        }
+    for (const [index, heading] of columns.entries()) {
+        headingIndex.set(heading, index);
     }
-    const aidIdx = headingIndex.get("AID");
-    const nameIdx = headingIndex.get("AssayName");
-    const targetIdx = headingIndex.get("TargetName");
-    const outcomeIdx = headingIndex.get("ActivityOutcome");
-    const valueIdx = headingIndex.get("ActivityValue");
+    const aidIdx = headingIndex.get(ASSAY_HEADINGS.aid);
+    const nameIdx = headingIndex.get(ASSAY_HEADINGS.assayName);
+    const targetIdx = headingIndex.get(ASSAY_HEADINGS.targetAccession);
+    const outcomeIdx = headingIndex.get(ASSAY_HEADINGS.activityOutcome);
+    const valueIdx = headingIndex.get(ASSAY_HEADINGS.activityValue);
     const results = [];
     for (const row of rows) {
         const cells = row.Cell ?? [];
+        // An empty cell is the empty string, which carries no value.
         const getCellStr = (idx) => {
-            if (idx === undefined || idx >= cells.length)
-                return null;
-            return cells[idx]?.sval ?? null;
-        };
-        const getCellNum = (idx) => {
-            if (idx === undefined || idx >= cells.length)
+            if (idx === undefined)
                 return null;
             const cell = cells[idx];
-            if (cell?.fval !== undefined)
-                return cell.fval;
-            if (cell?.intval !== undefined)
-                return cell.intval;
-            return null;
+            return cell !== undefined && cell !== "" ? cell : null;
         };
+        const getCellNum = (idx) => parseWireNumber(getCellStr(idx));
         results.push({
             aid: getCellNum(aidIdx) ?? 0,
             assayName: getCellStr(nameIdx),

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

@@ -3,6 +3,10 @@
  *
  * Used by §3.11 (Key Papers), §3.10.4 (Preclinical literature), and the
  * pubmed-index Phase-1 collector.
+ *
+ * Absence policy: NCBI E-utilities omits the key of an absent value, and it
+ * never sends an explicit `null`. Thus a maybe-absent field carries
+ * `.optional()`, not `.nullable()`.
  */
 import { type ArticleDetail, type ArticleSection, type FullTextResult, type PubmedSearchOptions, type PubMedSummary } from "../../literature/sources/pubmed.js";
 export type { PubMedSummary, ArticleDetail, ArticleSection, FullTextResult };

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

@@ -3,6 +3,10 @@
  *
  * Used by §3.11 (Key Papers), §3.10.4 (Preclinical literature), and the
  * pubmed-index Phase-1 collector.
+ *
+ * Absence policy: NCBI E-utilities omits the key of an absent value, and it
+ * never sends an explicit `null`. Thus a maybe-absent field carries
+ * `.optional()`, not `.nullable()`.
  */
 import { createPubmedSource, } from "../../literature/sources/pubmed.js";
 function pubmedSource(ncbiApiKey) {

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

@@ -2,7 +2,12 @@
  * Pure async client functions for STRING DB protein-protein interactions.
  *
  * Used by §3.8 (PPI Network).
+ *
+ * Absence policy: STRING omits the key of an absent value, and it never sends
+ * an explicit `null`. Thus a maybe-absent field carries `.optional()`, not
+ * `.nullable()`.
  */
+import { z } from "zod";
 export interface StringInteraction {
     proteinA: string;
     proteinB: string;
@@ -25,6 +30,53 @@ export interface InteractionOptions {
     minScore?: number;
     limit?: number;
 }
+export declare const StringInteractionSchema: z.ZodPipe<z.ZodObject<{
+    preferredName_A: z.ZodOptional<z.ZodString>;
+    preferredName_B: z.ZodOptional<z.ZodString>;
+    score: z.ZodOptional<z.ZodNumber>;
+    escore: z.ZodOptional<z.ZodNumber>;
+    dscore: z.ZodOptional<z.ZodNumber>;
+    tscore: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodTransform<{
+    proteinA: string;
+    proteinB: string;
+    score: number;
+    experimentalScore: number | undefined;
+    databaseScore: number | undefined;
+    textminingScore: number | undefined;
+}, {
+    preferredName_A?: string | undefined;
+    preferredName_B?: string | undefined;
+    score?: number | undefined;
+    escore?: number | undefined;
+    dscore?: number | undefined;
+    tscore?: number | undefined;
+}>>;
+export declare const StringEnrichmentSchema: z.ZodPipe<z.ZodObject<{
+    category: z.ZodOptional<z.ZodString>;
+    term: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    p_value: z.ZodOptional<z.ZodNumber>;
+    fdr: z.ZodOptional<z.ZodNumber>;
+    number_of_genes: z.ZodOptional<z.ZodNumber>;
+    preferredNames: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodTransform<{
+    category: string;
+    term: string;
+    description: string;
+    pValue: number;
+    fdr: number;
+    geneCount: number;
+    genes: string[];
+}, {
+    category?: string | undefined;
+    term?: string | undefined;
+    description?: string | undefined;
+    p_value?: number | undefined;
+    fdr?: number | undefined;
+    number_of_genes?: number | undefined;
+    preferredNames?: string[] | undefined;
+}>>;
 /** Fetch interaction partners (one-hop) for the given identifiers. */
 export declare function getInteractionPartners(identifiers: string[], options?: InteractionOptions): Promise<StringInteraction[]>;
 /**

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

@@ -2,6 +2,10 @@
  * Pure async client functions for STRING DB protein-protein interactions.
  *
  * Used by §3.8 (PPI Network).
+ *
+ * Absence policy: STRING omits the key of an absent value, and it never sends
+ * an explicit `null`. Thus a maybe-absent field carries `.optional()`, not
+ * `.nullable()`.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";
@@ -23,7 +27,7 @@ function buildParams(identifiers, species, extra = {}) {
 // `.transform(...)` half normalizes it into the `StringInteraction` we return. Parsing IS
 // the validation: `apiFetchValidated` runs this over the JSON, so a field whose type drifts
 // is rejected as `invalid_response` rather than silently mis-mapped.
-const StringInteractionSchema = z
+export const StringInteractionSchema = z
     .object({
     preferredName_A: z.string().optional(),
     preferredName_B: z.string().optional(),
@@ -40,10 +44,11 @@ const StringInteractionSchema = z
     databaseScore: d.dscore ?? undefined,
     textminingScore: d.tscore ?? undefined,
 }));
-// One STRING enrichment row. `preferredNames` legitimately arrives as either a string array
-// or a single comma-joined string, so the schema accepts the union and the transform folds
-// both into a `string[]`.
-const StringEnrichmentSchema = z
+// One STRING enrichment row. The `/api/json` renderer sends `preferredNames` as a
+// JSON array of gene names on every row, thus the schema declares an array. A
+// comma-joined string is a form of the tsv renderer, which this client never
+// calls.
+export const StringEnrichmentSchema = z
     .object({
     category: z.string().optional(),
     term: z.string().optional(),
@@ -51,7 +56,7 @@ const StringEnrichmentSchema = z
     p_value: z.number().optional(),
     fdr: z.number().optional(),
     number_of_genes: z.number().optional(),
-    preferredNames: z.union([z.array(z.string()), z.string()]).optional(),
+    preferredNames: z.array(z.string()).optional(),
 })
     .transform((d) => ({
     category: d.category ?? "",
@@ -60,7 +65,7 @@ const StringEnrichmentSchema = z
     pValue: d.p_value ?? 1,
     fdr: d.fdr ?? 1,
     geneCount: d.number_of_genes ?? 0,
-    genes: Array.isArray(d.preferredNames) ? d.preferredNames : (d.preferredNames ?? "").split(",").filter(Boolean),
+    genes: d.preferredNames ?? [],
 }));
 /** Fetch interaction partners (one-hop) for the given identifiers. */
 export async function getInteractionPartners(identifiers, options = {}) {

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

@@ -8,6 +8,10 @@
  *   - Protein family text — used together with IUPHAR family-target
  *     resolution to identify sibling receptors in the same pharmacological
  *     family (replaces the hand-curated RELATED_FAMILY_UNIPROTS map).
+ *
+ * Absence policy: the OpenAPI document of UniProt marks no field as required,
+ * and the API omits the key of an absent value. Thus a maybe-absent field
+ * carries `.optional()`, not `.nullable()`.
  */
 export interface UniProtRecord {
     primaryAccession: string;

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

@@ -8,6 +8,10 @@
  *   - Protein family text — used together with IUPHAR family-target
  *     resolution to identify sibling receptors in the same pharmacological
  *     family (replaces the hand-curated RELATED_FAMILY_UNIPROTS map).
+ *
+ * Absence policy: the OpenAPI document of UniProt marks no field as required,
+ * and the API omits the key of an absent value. Thus a maybe-absent field
+ * carries `.optional()`, not `.nullable()`.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";

package/dist/tools/research/context7-docs.d.ts

@@ -5,7 +5,12 @@
  * documentation and code examples at runtime. Two-step flow:
  * 1. resolveLibraryId — find the Context7 library ID for a package name
  * 2. queryDocs — query documentation for a resolved library
+ *
+ * Absence policy: the OpenAPI document of Context7 marks no field as nullable,
+ * and the sampled payloads carry no explicit `null`. Thus an absent value is an
+ * omitted key, and a maybe-absent field carries `.optional()`.
  */
+import { z } from "zod";
 type ResolveLibraryIdOutput = {
     found: false;
 } | {
@@ -20,6 +25,24 @@ type QueryDocsOutput = {
     found: true;
     documentation: string;
 };
+export declare const Context7SearchResponseSchema: z.ZodObject<{
+    results: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const Context7DocsResponseSchema: z.ZodObject<{
+    snippets: z.ZodArray<z.ZodObject<{
+        codeTitle: z.ZodString;
+        codeDescription: z.ZodString;
+        codeId: z.ZodString;
+        codeList: z.ZodArray<z.ZodObject<{
+            language: z.ZodString;
+            code: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const resolveLibraryIdTool: import("../define-tool.js").Tool<{
     libraryName: string;
     query: string;

package/dist/tools/research/context7-docs.js

@@ -5,19 +5,42 @@
  * documentation and code examples at runtime. Two-step flow:
  * 1. resolveLibraryId — find the Context7 library ID for a package name
  * 2. queryDocs — query documentation for a resolved library
+ *
+ * Absence policy: the OpenAPI document of Context7 marks no field as nullable,
+ * and the sampled payloads carry no explicit `null`. Thus an absent value is an
+ * omitted key, and a maybe-absent field carries `.optional()`.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
 const CONTEXT7_BASE = "https://context7.com/api/v1";
-// Raw Context7 wire shapes, validated at the fetch boundary. `id`/`name` stay
+// Raw Context7 wire shapes, validated at the fetch boundary. `id`/`title` stay
 // required — they are read without a guard — while genuinely-optional fields
 // carry `.optional()` so a partial-but-valid response still parses.
-const Context7SearchResponseSchema = z.object({
-    results: z.array(z.object({ id: z.string(), name: z.string(), description: z.string().nullable().optional() })).optional(),
+export const Context7SearchResponseSchema = z.object({
+    results: z.array(z.object({ id: z.string(), title: z.string(), description: z.string().nullable().optional() })).optional(),
+});
+// The docs route answers one `snippets` array, and each snippet holds its code in
+// `codeList`. There is no single documentation text on the wire, thus the tool
+// composes one from the snippets below.
+export const Context7DocsResponseSchema = z.object({
+    snippets: z.array(z.object({
+        codeTitle: z.string(),
+        codeDescription: z.string(),
+        codeId: z.string(),
+        codeList: z.array(z.object({ language: z.string(), code: z.string() })),
+    })),
 });
-const Context7DocsResponseSchema = z.object({ content: z.string().optional() });
+/** Render the snippets of one docs answer as a single text, in the layout of the Context7 text route. */
+function renderSnippets(snippets) {
+    return snippets
+        .map((snippet) => {
+        const code = snippet.codeList.map((example) => `\`\`\`${example.language}\n${example.code}\n\`\`\``).join("\n\n");
+        return `### ${snippet.codeTitle}\n\nSource: ${snippet.codeId}\n\n${snippet.codeDescription}\n\n${code}`;
+    })
+        .join("\n\n--------------------------------\n\n");
+}
 export const resolveLibraryIdTool = defineTool({
     id: "resolve_library_id",
     description: "Resolve a package name (e.g., 'scanpy', 'DESeq2', 'scikit-learn') to a Context7 library ID. Call this BEFORE `query_docs` to get the library ID needed for documentation lookup. Returns matching libraries ranked by relevance.",
@@ -37,7 +60,9 @@ export const resolveLibraryIdTool = defineTool({
         return ok({
             found: true,
             libraryId: best.id,
-            name: best.name,
+            // The display name of a library is `title` on the wire. The output keeps
+            // the `name` key, because that key is the contract that a caller reads.
+            name: best.title,
             description: best.description ?? "",
         });
     },
@@ -46,15 +71,30 @@ export const queryDocsTool = defineTool({
     id: "query_docs",
     description: "Query up-to-date documentation and code examples for a library. You must call `resolve_library_id` first to get the libraryId. Use this to verify function signatures, parameters, and usage patterns before writing code.",
     inputSchema: z.object({
-        libraryId: z.string().describe("Context7 library ID from `resolve_library_id` (for example '/scverse/scanpy')."),
+        libraryId: z.string().describe("Context7 library ID exactly as `resolve_library_id` gave it — an owner and a library, for example '/scverse/scanpy'."),
         query: z.string().describe("Specific question about the library (e.g., 'rank_genes_groups function parameters and usage')."),
     }),
     describeCall: "none",
     execute: async ({ libraryId, query }) => {
-        const result = await apiFetchValidated(`${CONTEXT7_BASE}/docs?libraryId=${encodeURIComponent(libraryId)}&query=${encodeURIComponent(query)}`, Context7DocsResponseSchema, { maxRetries: 1 });
-        if (result.isErr())
+        // The library id is the path of the route, not a query parameter. Each
+        // segment is encoded on its own, thus the separators of the id survive and
+        // a leading or trailing slash makes no difference.
+        const path = libraryId
+            .split("/")
+            .filter((segment) => segment !== "")
+            .map((segment) => encodeURIComponent(segment))
+            .join("/");
+        const result = await apiFetchValidated(`${CONTEXT7_BASE}/${path}?type=json&topic=${encodeURIComponent(query)}`, Context7DocsResponseSchema, {
+            maxRetries: 1,
+        });
+        if (result.isErr()) {
+            // Context7 answers 404 for a library that it does not hold. A stale id is
+            // an expected outcome, thus it becomes a data variant.
+            if (result.error.type === "http_status" && result.error.status === 404)
+                return ok({ found: false });
             throw new Error(`Context7 query failed: ${describeApiError(result.error)}`);
-        const documentation = result.value.content ?? "";
+        }
+        const documentation = renderSnippets(result.value.snippets);
         // No documentation for the query is an expected outcome.
         if (!documentation)
             return ok({ found: false });

package/dist/tools/research/search-github-repos.d.ts

@@ -4,6 +4,10 @@
  * (lower rate limit); `GITHUB_TOKEN` raises the limit.
  *
  * Same wire call and envelope as the legacy tool. Stateless HTTP; no deps.
+ *
+ * Absence policy: the OpenAPI document of GitHub marks `description` and
+ * `language` as required and nullable, thus an absent value is an explicit
+ * `null`. The OpenAPI document gives the modifier of each field.
  */
 type SearchGithubReposOutput = {
     success: false;

package/dist/tools/research/search-github-repos.js

@@ -4,6 +4,10 @@
  * (lower rate limit); `GITHUB_TOKEN` raises the limit.
  *
  * Same wire call and envelope as the legacy tool. Stateless HTTP; no deps.
+ *
+ * Absence policy: the OpenAPI document of GitHub marks `description` and
+ * `language` as required and nullable, thus an absent value is an explicit
+ * `null`. The OpenAPI document gives the modifier of each field.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";

package/dist/workflows/execute-target-assessment.js

@@ -149,7 +149,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
         // terminal block dispatches `markFailed({kind: "target-unresolved"})`.
         await emitProgress(deps.pool, logger, input.assessmentId, "resolving");
         const resolved = await DBOS.runStep(async () => {
-            const r = await resolveTarget(input.target);
+            const r = await resolveTarget(input.target, logger);
             return {
                 assessmentId: input.assessmentId,
                 goal: input.goal ?? null,
@@ -166,7 +166,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
         // and `Phase1Bundle` is reconstructed by manifest key below.
         await emitProgress(deps.pool, logger, input.assessmentId, "collecting");
         const manifest = COLLECTOR_MANIFEST;
-        const collectorCtx = { ncbiApiKey: deps.ncbiApiKey };
+        const collectorCtx = { ncbiApiKey: deps.ncbiApiKey, logger };
         const collectorPairs = await Promise.all(manifest.map((entry) => DBOS.runStep(() => entry.run(resolved, collectorCtx), {
             name: `ta-collector:${entry.id}`,
         })
@@ -285,7 +285,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
         const [perModulatorFaersResults, perTrialAesResults, perModulatorPolypharmResults, perClassDrugAesResults] = await Promise.all([
             runFanoutBlock(triageShortlist, "modulator-faers", (item) => item.moleculeChemblId, faersForOneModulator),
             runFanoutBlock(trialItems, "trial-aes", (item) => item.nctId, aesForOneTrial),
-            runFanoutBlock(polypharmItems, "modulator-polypharm", (item) => item.moleculeChemblId, polypharmForOneModulator),
+            runFanoutBlock(polypharmItems, "modulator-polypharm", (item) => item.moleculeChemblId, (item) => polypharmForOneModulator(item, logger)),
             runFanoutBlock(classDrugItems, "class-drug-aes", (item) => item.moleculeChemblId, aesForOneClassDrug),
         ]);
         const phase3 = {
@@ -307,7 +307,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
             model: deps.decisionModel,
             ...(deps.usageRecorder ? { usageRecorder: deps.usageRecorder } : {}),
         };
-        const phase4 = await DBOS.runStep(() => phase4Assemble(deps.pool, phase3, annotatorDeps), {
+        const phase4 = await DBOS.runStep(() => phase4Assemble(deps.pool, phase3, annotatorDeps, logger), {
             name: "ta-phase4-assemble",
         });
         // (§5.8-pre) Approval-precedent grounding — one deterministic openFDA

package/dist/workflows/target-assessment/assemblers/orchestrator.d.ts

@@ -21,6 +21,7 @@ import type { Phase2Bundle } from "../steps/phase2-aggregate.js";
 import type { Phase3Bundle } from "../steps/phase3-aggregate.js";
 import type { ResolvedTarget } from "../schemas.js";
 import type { Pool } from "pg";
+import type { Logger } from "../../../lib/logger.js";
 import type { ClinicalConsequenceAnnotatorDeps } from "../lib/clinical-consequence-annotator.js";
 import { HIGH_EXPRESSION_TPM_THRESHOLD } from "../lib/expression-constants.js";
 export { HIGH_EXPRESSION_TPM_THRESHOLD };
@@ -52,7 +53,7 @@ export declare function assembleTractability(resolved: ResolvedTarget, ot: OpenT
  * attached here — phase5-persist computes it after synthesis is stamped
  * so the final derived values reflect liability bullets and safety flags.
  */
-export declare function assembleDossier(pool: Pool, phase2: Phase2Bundle, phase3?: Phase3Bundle, annotatorDeps?: ClinicalConsequenceAnnotatorDeps): Promise<DossierBody>;
+export declare function assembleDossier(pool: Pool, phase2: Phase2Bundle, phase3?: Phase3Bundle, annotatorDeps?: ClinicalConsequenceAnnotatorDeps, logger?: Logger): Promise<DossierBody>;
 type ReconcileFaersClassPrecedent = {
     coverage?: "available" | "queried_no_data" | "not_loaded";
     data?: {

package/dist/workflows/target-assessment/assemblers/orchestrator.js

@@ -223,7 +223,7 @@ export function assembleTractability(resolved, ot, drugs) {
  * attached here — phase5-persist computes it after synthesis is stamped
  * so the final derived values reflect liability bullets and safety flags.
  */
-export async function assembleDossier(pool, phase2, phase3, annotatorDeps) {
+export async function assembleDossier(pool, phase2, phase3, annotatorDeps, logger) {
     const fanout = phase3?.fanout;
     const faersAgg = aggregateFaersAcrossModulators(fanout);
     const trialAesAgg = aggregateTrialAes(fanout);
@@ -235,8 +235,8 @@ export async function assembleDossier(pool, phase2, phase3, annotatorDeps) {
     const familyComplexesCollector = phase2.phase1.collectors.familyComplexes;
     const familyComplexesBundle = familyComplexesCollector.coverage === "available" ? familyComplexesCollector.data : null;
     const [onTargetChemblIds, familySiblingUniprots] = await Promise.all([
-        resolveOnTargetChemblIds(assessmentUniprot),
-        resolveFamilySiblingUniprots(assessmentUniprot || geneSymbol),
+        resolveOnTargetChemblIds(assessmentUniprot, logger),
+        resolveFamilySiblingUniprots(assessmentUniprot || geneSymbol, logger),
     ]);
     const offTargetPanel = aggregateOffTargetPanel(phase2, fanout, assessmentUniprot, geneSymbol, familyComplexesBundle, onTargetChemblIds);
     if (offTargetPanel) {