@inflexa-ai/harness 0.17.0 → 0.18.0

package/dist/tools/iterate-report.js

@@ -413,6 +413,7 @@ export const planReportTool = defineTool({
         "existing preview with `modifications` needs no brief — you may go " +
         "straight to `submit_report`.)",
     inputSchema: z.object({}),
+    describeCall: "none",
     executionMode: "inline",
     execute: async () => ok({
         schema: REPORT_BRIEF_JSON_SCHEMA,
@@ -472,6 +473,7 @@ export function createReportSubmitTool(deps) {
             "as an `error` string. Returns the preview id + version and emits a " +
             "preview card.",
         inputSchema: submitReportInputSchema,
+        describeCall: "none",
         execute: async (input, ctx) => {
             // The brief rides as `unknown` so its ~12k schema stays off the
             // always-on tool surface. Validate it here and return issues as DATA

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

@@ -58,6 +58,8 @@ export interface ChemblPolypharmHit {
     moleculeChemblId: string;
     targetChemblId: string;
     targetName: string | null;
+    /** The assay the reported activity was measured in, when ChEMBL names one. */
+    assayChemblId: string | null;
     standardType: string | null;
     standardValue: number | null;
     standardUnits: string | null;

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

@@ -431,6 +431,7 @@ export async function getModulatorPolypharmacology(moleculeChemblId, options = {
                 moleculeChemblId,
                 targetChemblId: tid,
                 targetName: null,
+                assayChemblId: raw.assay_chembl_id ?? null,
                 standardType: raw.standard_type ?? null,
                 standardValue: parseNumeric(raw.standard_value),
                 standardUnits: raw.standard_units ?? null,

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

@@ -0,0 +1,42 @@
+/**
+ * Pure async client functions for the Monarch Initiative association API.
+ *
+ * Monarch curates human gene→phenotype annotations (HPO, from HPOA/OMIM/
+ * Orphanet): *human* loss-of-function evidence, meaning what is observed in
+ * people carrying variation in the gene, as opposed to a mouse knockout's
+ * phenotype or an aggregate gene-disease association score.
+ *
+ * Each phenotype association carries its HPO ancestor closure, which is what
+ * lets a consumer resolve the phenotype onto an organ system by identifier
+ * rather than by matching prose.
+ *
+ * The API is keyless and public.
+ */
+/** A curated human phenotype attributed to variation in the gene. */
+export interface MonarchPhenotypeAssociation {
+    /** HPO term id, e.g. `HP:0001392`. */
+    readonly hpoId: string;
+    readonly label: string;
+    /** The term's HPO ancestor closure, for identifier-based organ resolution. */
+    readonly ancestorIds: string[];
+    /** PMIDs (as `PMID:…` curies) cited by the annotation. */
+    readonly publications: string[];
+    /** The disease the phenotype was annotated under, when the annotation names one. */
+    readonly diseaseContext: string | null;
+    /** Share of affected individuals showing the phenotype, when annotated. */
+    readonly frequencyPercent: number | null;
+    readonly primaryKnowledgeSource: string | null;
+}
+export interface MonarchGeneProfile {
+    /** The curie the gene was queried by, e.g. `HGNC:1097`. */
+    readonly geneCurie: string;
+    readonly phenotypes: MonarchPhenotypeAssociation[];
+}
+/**
+ * Curated human phenotype associations for one gene.
+ *
+ * `geneCurie` is a prefixed identifier Monarch resolves — an HGNC id
+ * (`HGNC:1097`) or an NCBI gene id (`NCBIGene:673`). A gene Monarch does not
+ * hold returns an empty profile rather than an error.
+ */
+export declare function getGenePhenotypeProfile(geneCurie: string): Promise<MonarchGeneProfile>;

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

@@ -0,0 +1,100 @@
+/**
+ * Pure async client functions for the Monarch Initiative association API.
+ *
+ * Monarch curates human gene→phenotype annotations (HPO, from HPOA/OMIM/
+ * Orphanet): *human* loss-of-function evidence, meaning what is observed in
+ * people carrying variation in the gene, as opposed to a mouse knockout's
+ * phenotype or an aggregate gene-disease association score.
+ *
+ * Each phenotype association carries its HPO ancestor closure, which is what
+ * lets a consumer resolve the phenotype onto an organ system by identifier
+ * rather than by matching prose.
+ *
+ * The API is keyless and public.
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError, isUnexpectedApiError } from "./api-utils.js";
+const MONARCH_BASE = "https://api-v3.monarchinitiative.org/v3/api";
+/** Row cap per association category — a well-annotated gene carries a few hundred. */
+const ASSOCIATION_ROW_CAP = 300;
+/** The closure arrays make these responses large; the default timeout is short for them. */
+const REQUEST_TIMEOUT_MS = 120_000;
+const HUMAN_TAXON = "NCBITaxon:9606";
+/** Phenotype terms live in the HPO namespace; a model-organism term would not. */
+const HPO_NAMESPACE = "HP";
+/**
+ * One association row. Every field is optional because Monarch returns the same
+ * envelope for every category and populates only what applies; the reader below
+ * treats a missing field as absent rather than trusting the wire.
+ */
+const MonarchAssociationSchema = z.object({
+    subject_taxon: z.string().nullish(),
+    object: z.string().optional(),
+    object_label: z.string().nullish(),
+    object_closure: z.array(z.string()).nullish(),
+    publications: z.array(z.string()).nullish(),
+    primary_knowledge_source: z.string().nullish(),
+    disease_context_qualifier: z.string().nullish(),
+    has_percentage: z.number().nullish(),
+});
+const MonarchAssociationPageSchema = z.object({
+    items: z.array(MonarchAssociationSchema).optional(),
+});
+async function fetchAssociations(geneCurie, category) {
+    const params = new URLSearchParams({
+        subject: geneCurie,
+        category,
+        limit: String(ASSOCIATION_ROW_CAP),
+    });
+    const res = await apiFetchValidated(`${MONARCH_BASE}/association?${params.toString()}`, MonarchAssociationPageSchema, {
+        timeoutMs: REQUEST_TIMEOUT_MS,
+    });
+    if (res.isErr()) {
+        // A 4xx means the gene curie is not one Monarch holds — an expected
+        // "not found", returned as an empty page. Anything else is a real
+        // failure and surfaces.
+        if (isUnexpectedApiError(res.error))
+            throw new Error(describeApiError(res.error));
+        return [];
+    }
+    return res.value.items ?? [];
+}
+/**
+ * Human phenotype annotations only.
+ *
+ * Monarch serves a gene's phenotype edges from several annotation sets; the
+ * filter keeps the rows whose subject is the human gene and whose object is an
+ * HPO term, so model-organism phenotypes stay with the collector that owns them.
+ */
+function toPhenotype(row) {
+    if (!row.object || !row.object.startsWith(`${HPO_NAMESPACE}:`))
+        return null;
+    if (row.subject_taxon != null && row.subject_taxon !== HUMAN_TAXON)
+        return null;
+    return {
+        hpoId: row.object,
+        label: row.object_label ?? "",
+        ancestorIds: row.object_closure ?? [],
+        publications: row.publications ?? [],
+        diseaseContext: row.disease_context_qualifier ?? null,
+        frequencyPercent: row.has_percentage ?? null,
+        primaryKnowledgeSource: row.primary_knowledge_source ?? null,
+    };
+}
+/**
+ * Curated human phenotype associations for one gene.
+ *
+ * `geneCurie` is a prefixed identifier Monarch resolves — an HGNC id
+ * (`HGNC:1097`) or an NCBI gene id (`NCBIGene:673`). A gene Monarch does not
+ * hold returns an empty profile rather than an error.
+ */
+export async function getGenePhenotypeProfile(geneCurie) {
+    const rows = await fetchAssociations(geneCurie, "biolink:GeneToPhenotypicFeatureAssociation");
+    const phenotypes = [];
+    for (const row of rows) {
+        const p = toPhenotype(row);
+        if (p)
+            phenotypes.push(p);
+    }
+    return { geneCurie, phenotypes };
+}

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

@@ -16,6 +16,7 @@ export function createBuildReportTool(state) {
             "Always use this — never invoke a build script directly. Returns " +
             "structured errors with line numbers when the template is broken.",
         inputSchema: z.object({}),
+        describeCall: "none",
         execute: async () => {
             return ok(await renderReport({
                 versionDir: state.versionDir,

package/dist/tools/report/mint-preview-url.js

@@ -24,6 +24,7 @@ export function createMintPreviewUrlTool(state) {
         inputSchema: z.object({
             version: z.number().optional().describe("Version to mint for. Defaults to the iteration's current version."),
         }),
+        describeCall: "none",
         execute: async (input) => {
             const version = input.version ?? state.currentVersion;
             const result = await state.previews.mintPreviewAccess(state.resourceId, state.previewId);

package/dist/tools/report/preview-snapshot.js

@@ -47,6 +47,7 @@ export function createPreviewSnapshotTool(state) {
                 .optional()
                 .describe("Optional extra wait in ms after the theme-ready event (e.g., for chart paint). Capped at 30s."),
         }),
+        describeCall: "none",
         execute: async (input) => {
             let url = state.urlCell.url;
             const expiresAt = state.urlCell.expiresAt;

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

@@ -42,6 +42,7 @@ export function createSubmitReportTool(state) {
                 "samples — the rest had no QC row'. " +
                 "Leave empty when the report shipped cleanly."),
         }),
+        describeCall: "none",
         execute: async (input) => {
             const problems = [];
             // 1. report.html.j2 exists — the report itself, as opposed to the

package/dist/tools/report/version-fs.js

@@ -44,6 +44,7 @@ export function createVersionFsTools(state) {
             path: z.string().min(1),
             content: z.string(),
         }),
+        describeCall: "none",
         execute: async ({ path, content }) => {
             const resolved = resolveAgentPath(path, state.versionDir);
             if (resolved.kind === "out_of_scope") {
@@ -73,6 +74,7 @@ export function createVersionFsTools(state) {
             oldText: z.string().min(1),
             newText: z.string(),
         }),
+        describeCall: "none",
         execute: async ({ path, oldText, newText }) => {
             const resolved = resolveAgentPath(path, state.versionDir);
             if (resolved.kind === "out_of_scope") {
@@ -112,6 +114,7 @@ export function createVersionFsTools(state) {
         inputSchema: z.object({
             path: z.string().min(1),
         }),
+        describeCall: "none",
         execute: async ({ path }) => {
             const resolved = resolveAgentPath(path, state.versionDir);
             if (resolved.kind === "out_of_scope") {
@@ -148,6 +151,7 @@ export function createVersionFsTools(state) {
         inputSchema: z.object({
             path: z.string().min(1),
         }),
+        describeCall: "none",
         execute: async ({ path }) => {
             const resolved = resolveAgentPath(path, state.versionDir);
             if (resolved.kind === "out_of_scope") {

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

@@ -0,0 +1,134 @@
+/**
+ * The authoring tool surface over the draft operations.
+ *
+ * The factory closes over a private draft holder and the pinned snapshot. It gives eight tools and a
+ * read of the current draft. The tools read no ambient state, thus two factories hold two independent
+ * drafts.
+ *
+ * Each tool maps its flat input onto a core operation, and it applies the pure operation. The holder
+ * swaps only on a landed operation. A refused operation returns typed data in the ok channel, and the
+ * error channel stays for an unexpected failure.
+ *
+ * The primitive admits a flat object input only. Thus a destination is four optional fields, and not a
+ * nested union. A conflict between the flat fields refuses before the core runs.
+ */
+import { z } from "zod";
+import { type DraftRefusal } from "../../report-model/draft-operations.js";
+import { type OutlineEntry, type ReadableBlock } from "../../report-model/draft-read.js";
+import { type FinishResult } from "../../report-model/draft-finish.js";
+import { type DraftDocument } from "../../report-model/draft.js";
+import type { ReportSnapshot } from "../../report-model/reference-resolver.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`. */
+declare const addBlockInput: z.ZodObject<{
+    block: z.ZodUnion<readonly [z.ZodType<import("../../report-model/draft.js").DraftBlock, unknown, z.core.$ZodTypeInternals<import("../../report-model/draft.js").DraftBlock, unknown>>, z.ZodUnknown]>;
+    parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    place: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        end: "end";
+        start: "start";
+    }>>>;
+    before: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    after: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * The change payload is a title for a section target, or a block for an atom target, and exactly one of
+ * the two. Both fields are absentable, because a section retitle names no block. Zod 4 treats a bare
+ * `z.unknown()` as a required key, thus an optional marker is what makes the retitle call representable.
+ */
+declare const changeBlockInput: z.ZodObject<{
+    targetId: z.ZodString;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    block: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<import("../../report-model/draft.js").DraftBlock, unknown, z.core.$ZodTypeInternals<import("../../report-model/draft.js").DraftBlock, unknown>>, z.ZodUnknown]>>;
+}, z.core.$strip>;
+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";
+        start: "start";
+    }>>>;
+    before: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    after: z.ZodOptional<z.ZodNullable<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. */
+declare const readBlockInput: z.ZodObject<{
+    targetId: z.ZodString;
+}, z.core.$strip>;
+declare const setTitleInput: z.ZodObject<{
+    title: z.ZodString;
+}, z.core.$strip>;
+declare const finishDraftInput: z.ZodObject<{}, z.core.$strip>;
+export type AddBlockInput = z.infer<typeof addBlockInput>;
+export type ChangeBlockInput = z.infer<typeof changeBlockInput>;
+export type RemoveBlockInput = z.infer<typeof removeBlockInput>;
+export type MoveBlockInput = z.infer<typeof moveBlockInput>;
+export type ReadOutlineInput = z.infer<typeof readOutlineInput>;
+export type ReadBlockInput = z.infer<typeof readBlockInput>;
+export type SetTitleInput = z.infer<typeof setTitleInput>;
+export type FinishDraftInput = z.infer<typeof finishDraftInput>;
+/** One container that an operation changed, and the child order inside it after the operation. */
+export interface ChangedContainer {
+    /** The section that holds the children. It is absent when the container is the root. */
+    parentId?: string;
+    children: OutlineEntry[];
+}
+/**
+ * The result of a mutation tool. A refusal carries the typed reason.
+ *
+ * A landing carries the child order of each container that it changed, and not the whole outline. A whole
+ * outline costs the size of the draft on every landing, thus composing a report of n blocks would spend
+ * n-squared outline entries of agent context to author it. Only the container that the operation touched
+ * can surprise the agent: it chose the id, and the rest of the tree did not move. `read_outline` stays
+ * the way to read the whole draft, and it costs one call when the agent wants one.
+ *
+ * A move across two containers reports both. An operation that changes no child order reports none.
+ */
+export type MutationResult = {
+    applied: true;
+    changed: ChangedContainer[];
+} | {
+    applied: false;
+    refusal: DraftRefusal;
+};
+/** The result of `read_outline`. */
+export interface OutlineResult {
+    outline: OutlineEntry[];
+}
+/** The result of `read_block`. An absent block is an expected outcome, thus it stays in the ok channel. */
+export type ReadBlockResult = {
+    found: true;
+    block: ReadableBlock;
+} | {
+    found: false;
+};
+/** The state that the factory closes over. */
+export interface ReportAuthoringState {
+    readonly snapshot: ReportSnapshot;
+    /** The draft to start from. The default is an empty draft. */
+    readonly initialDraft?: DraftDocument;
+}
+/** The eight authoring tools, plus a read of the current draft. */
+export interface ReportAuthoringTools {
+    readonly add_block: Tool<AddBlockInput, MutationResult>;
+    readonly change_block: Tool<ChangeBlockInput, MutationResult>;
+    readonly remove_block: Tool<RemoveBlockInput, MutationResult>;
+    readonly move_block: Tool<MoveBlockInput, MutationResult>;
+    readonly set_title: Tool<SetTitleInput, MutationResult>;
+    readonly read_outline: Tool<ReadOutlineInput, OutlineResult>;
+    readonly read_block: Tool<ReadBlockInput, ReadBlockResult>;
+    readonly finish_draft: Tool<FinishDraftInput, FinishResult>;
+    currentDraft(): DraftDocument;
+}
+/**
+ * Make the eight authoring tools over one draft.
+ *
+ * The holder is a private `let`. Each tool reads the holder at call time, thus a landing through one tool
+ * shows in the next call of every tool. The holder swaps only inside `land`, thus a refused operation
+ * leaves the draft as it was.
+ */
+export declare function createReportAuthoringTools(state: ReportAuthoringState): ReportAuthoringTools;
+export {};