@inflexa-ai/harness 0.42.1 → 0.43.0

package/dist/tasks/derive-table-exec.js

@@ -1,22 +1,17 @@
 /**
  * The container of one report-session derivation, as a registered DBOS workflow.
  *
- * The `derive_table` tool runs inside one live chat turn, and a chat turn is not a workflow body. An await
- * of an exec under the callback transport calls `DBOS.recv`, which a workflow body alone can call. Thus the
+ * The `derive_table` tool runs inside one live chat turn, and a chat turn is not a workflow. An exec runs as
+ * a durable step of a workflow, and the reaper maps each container to the workflow that owns it. Thus the
  * container lives here, behind a registered workflow, and the tool starts it and awaits the handle.
  *
  * The shape is the shape of `tasks/extract-values.ts`: a body that a test drives directly, a registration
  * that closes over the construction-time deps, and a trigger that starts the workflow and gives the result
  * back. The tool holds the trigger as a plain function, thus no module under `tools/` imports DBOS.
  *
- * The body owns the whole machine lifetime. It creates the container, submits one exec, awaits the terminal
+ * The body owns the whole machine lifetime. It creates the container, runs one exec to its terminal
  * result, and tears the container down on both paths. A teardown fault reaches the log alone, because the
  * work is done by then.
- *
- * The exec id is `${workflowId}:${stepId}:${fnId}`, the one shape that `workflowIdFromExec` parses. A
- * callback host reads the owner workflow out of the exec id alone, thus a flat id makes the completion
- * callback unroutable and it lands as a `400`. The pull backstop still settles such an exec, but it pays
- * the quiet interval first.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { err, ok } from "neverthrow";
@@ -26,7 +21,7 @@ import { mintSandboxIdentity } from "../sandbox/identity.js";
 import { keepSuspendingRefusal } from "../sandbox/sandbox-error.js";
 import { suspensionOfSpawnRefusal } from "../workflows/suspension.js";
 import { buildDerivationExec, DERIVATION_DEADLINE_MS, DERIVATION_RESOURCES, DERIVE_RUN_LITERAL, DERIVE_STEP_LITERAL, } from "../tools/report-session/derive-table.js";
-/** The awaitExec callback. A derivation reports no live activity, thus the callback drops each event. */
+/** The exec progress callback. A derivation reports no live activity, thus the callback drops each event. */
 const noopEmit = () => { };
 /**
  * The body, exported so a test drives it without a registered workflow.
@@ -39,9 +34,6 @@ const noopEmit = () => { };
 export async function runDeriveTableExecBody(input, deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("derive-table-exec").with({ analysisId: input.analysisId });
     const workflowId = DBOS.workflowID ?? deriveTableExecWorkflowId(input.executionId);
-    // One workflow submits one exec, thus the function id is a constant. The three segments are what a
-    // callback host parses to find the workflow that awaits this exec.
-    const execId = `${workflowId}:${DERIVE_STEP_LITERAL}:fn-0`;
     const spawned = keepSuspendingRefusal(await deps.sandboxClient.createSandbox(forStep(input.runSession, DERIVE_STEP_LITERAL), { childWorkflowId: workflowId, resources: DERIVATION_RESOURCES, writableTail: input.writableTail }, mintSandboxIdentity(DERIVE_RUN_LITERAL)));
     if (spawned.isErr()) {
         const suspension = suspensionOfSpawnRefusal(spawned.error);
@@ -50,17 +42,15 @@ export async function runDeriveTableExecBody(input, deps) {
     }
     const sandbox = spawned.value;
     try {
-        // A checkpointed clock, not `Date.now()`: the await gates on this absolute deadline, and a
-        // wall-clock deadline that grew on replay would shift which loop iteration crosses it.
+        // A checkpointed clock, not `Date.now()`: a wall-clock deadline would grow on each recovery.
         const deadline = (await (deps.now ?? (() => DBOS.now()))()) + DERIVATION_DEADLINE_MS;
-        await deps.sandboxClient.submitExec(sandbox, buildDerivationExec({
+        const request = buildDerivationExec({
             script: input.script,
-            execId,
             workingDir: input.workingDir,
             inputs: input.inputs,
             output: input.output,
-        }));
-        return ok(await deps.sandboxClient.awaitExec(sandbox, execId, noopEmit, deadline));
+        });
+        return ok(await deps.sandboxClient.exec(sandbox, request, noopEmit, deadline));
     }
     finally {
         try {
@@ -78,12 +68,7 @@ export async function runDeriveTableExecBody(input, deps) {
 export function registerDeriveTableExecWorkflow(deps) {
     return DBOS.registerWorkflow((input) => runDeriveTableExecBody(input, deps), { name: "derive-table-exec" });
 }
-/**
- * The workflow id of one derivation.
- *
- * It carries exactly one colon, because `workflowIdFromExec` recovers the id by a strip of the last two
- * colon-delimited segments of the exec id. The execution id is unique already, thus no nonce joins it.
- */
+/** The workflow id of one derivation. The execution id is unique already, thus no nonce joins it. */
 export function deriveTableExecWorkflowId(executionId) {
     return `${DERIVE_RUN_LITERAL}:${executionId}`;
 }

package/dist/tasks/extract-values.d.ts

@@ -18,7 +18,7 @@ import type { Logger } from "../lib/logger.js";
 import type { ExtractionArm, ExtractionArtifact, ExtractionRequest } from "../report-model/production-resolver.js";
 import type { SandboxClient } from "../sandbox/client.js";
 import { type Suspension } from "../workflows/suspension.js";
-import type { ExecResult, SubmitExecBody } from "../sandbox/types.js";
+import type { ExecRequest, ExecResult } from "../sandbox/types.js";
 import { type ExtractValuesResult } from "./extract-values-script.js";
 export type { ExtractValuesResult } from "./extract-values-script.js";
 /**
@@ -60,7 +60,7 @@ export interface ExtractValuesWorkflowInput {
  *
  * The function is pure, thus a test asserts the command shape without a sandbox.
  */
-export declare function buildExtractionExec(analysisId: string, requests: readonly ExtractionRequest[], execId: string): SubmitExecBody;
+export declare function buildExtractionExec(analysisId: string, requests: readonly ExtractionRequest[]): ExecRequest;
 /**
  * Parse the script output from the exec result. A synthetic failure, a timeout, and a non-zero exit each
  * throw, because each means the script did not emit its map. A stdout that is not the map shape throws too.

package/dist/tasks/extract-values.js

@@ -35,7 +35,7 @@ const EXTRACTION_DEADLINE_MS = 300_000;
  * carries no file size. A later change can size it from the batch.
  */
 const EXTRACTION_RESOURCES = { cpu: 2, memoryGb: 8 };
-/** The awaitExec callback. The extraction pass reports no live activity, thus the callback drops each event. */
+/** The exec progress callback. The extraction pass reports no live activity, thus the callback drops each event. */
 const noopEmit = () => { };
 /**
  * Build the sandbox exec for one extraction pass. The command runs the fixed script through `python3 -c`.
@@ -50,11 +50,10 @@ const noopEmit = () => { };
  *
  * The function is pure, thus a test asserts the command shape without a sandbox.
  */
-export function buildExtractionExec(analysisId, requests, execId) {
+export function buildExtractionExec(analysisId, requests) {
     const scriptRequests = requests.map((request) => ({ path: request.path, format: request.format, hash: request.hash }));
     return {
         command: ["python3", "-c", EXTRACTION_SCRIPT],
-        execId,
         cwd: `/${analysisId}`,
         env: { [EXTRACTION_INPUT_ENV]: JSON.stringify(scriptRequests) },
         timeoutSeconds: Math.floor(EXTRACTION_DEADLINE_MS / 1000),
@@ -113,11 +112,9 @@ export async function runExtractValuesBody(input, deps) {
         }
         const sandbox = spawned.value;
         try {
-            // A checkpointed clock, not `Date.now()`: the await gates on this absolute deadline, and a
-            // wall-clock deadline that grew on replay would shift which loop iteration crosses it.
+            // A checkpointed clock, not `Date.now()`: a wall-clock deadline would grow on each recovery.
             const deadlineAbs = (await DBOS.now()) + EXTRACTION_DEADLINE_MS;
-            await deps.sandboxClient.submitExec(sandbox, buildExtractionExec(analysisId, requests, executionId));
-            const result = await deps.sandboxClient.awaitExec(sandbox, executionId, noopEmit, deadlineAbs);
+            const result = await deps.sandboxClient.exec(sandbox, buildExtractionExec(analysisId, requests), noopEmit, deadlineAbs);
             const map = parseExtractionOutput(result);
             await revoke("extract-values-completed");
             return ok(map);

package/dist/tools/bio/index.d.ts

@@ -34,5 +34,7 @@ export * from "./gene-preclinical-profile.js";
 export * from "./search-clinical-trials.js";
 export * from "./search-geo-datasets.js";
 export * from "./search-faers.js";
+export * from "./search-regulatory-approvals.js";
+export * from "./search-patents.js";
 export * from "./target-safety.js";
 export * from "./comptox.js";

package/dist/tools/bio/index.js

@@ -41,6 +41,9 @@ export * from "./gene-preclinical-profile.js";
 export * from "./search-clinical-trials.js";
 export * from "./search-geo-datasets.js";
 export * from "./search-faers.js";
+// Regulatory authorizations and patents (Amass)
+export * from "./search-regulatory-approvals.js";
+export * from "./search-patents.js";
 // Safety / toxicology
 export * from "./target-safety.js";
 export * from "./comptox.js";

package/dist/tools/bio/keys.d.ts

@@ -14,6 +14,7 @@ export interface BioToolKeys {
     readonly ncbi?: string;
     readonly github?: string;
     readonly semanticScholar?: string;
+    readonly amass?: string;
 }
 /**
  * The NCBI-backed literature tool, built from the shared key slice.
@@ -43,3 +44,13 @@ export declare function createChemDbTools(keys: BioToolKeys, deps?: {
     drugGeneInteractions: Tool;
     comptox: Tool;
 };
+/**
+ * The Amass tools: FDA and EMA authorizations, and patents.
+ *
+ * The key is optional. With no key, each tool is still built, and a call throws
+ * before it reaches Amass, the same as `comptox` without its EPA key.
+ */
+export declare function createAmassTools(keys: BioToolKeys): {
+    regulatoryApprovals: Tool;
+    patents: Tool;
+};

package/dist/tools/bio/keys.js

@@ -2,6 +2,8 @@ import { createComptoxTool } from "./comptox.js";
 import { createDrugGeneInteractionsTool } from "./drug-gene-interactions.js";
 import { createGeneDiseaseEvidenceTool } from "./gene-disease-evidence.js";
 import { createPubMedTool } from "./pubmed.js";
+import { createSearchPatentsTool } from "./search-patents.js";
+import { createSearchRegulatoryApprovalsTool } from "./search-regulatory-approvals.js";
 /**
  * The NCBI-backed literature tool, built from the shared key slice.
  *
@@ -39,3 +41,16 @@ export function createChemDbTools(keys, deps = {}) {
         comptox: createComptoxTool({ apiKey: keys.epaCcte }),
     };
 }
+/**
+ * The Amass tools: FDA and EMA authorizations, and patents.
+ *
+ * The key is optional. With no key, each tool is still built, and a call throws
+ * before it reaches Amass, the same as `comptox` without its EPA key.
+ */
+export function createAmassTools(keys) {
+    const apiKey = keys.amass ?? "";
+    return {
+        regulatoryApprovals: createSearchRegulatoryApprovalsTool({ apiKey }),
+        patents: createSearchPatentsTool({ apiKey }),
+    };
+}

package/dist/tools/bio/search-clinical-trials.d.ts

@@ -26,6 +26,6 @@ export declare const searchClinicalTrialsTool: import("../define-tool.js").Tool<
     query?: string | undefined;
     nctId?: string | undefined;
     phase?: "EARLY_PHASE1" | "PHASE1" | "PHASE2" | "PHASE3" | "PHASE4" | undefined;
-    status?: "RECRUITING" | "ACTIVE_NOT_RECRUITING" | "COMPLETED" | "NOT_YET_RECRUITING" | "TERMINATED" | "WITHDRAWN" | "SUSPENDED" | undefined;
+    status?: "SUSPENDED" | "RECRUITING" | "ACTIVE_NOT_RECRUITING" | "COMPLETED" | "NOT_YET_RECRUITING" | "TERMINATED" | "WITHDRAWN" | undefined;
 }, ClinicalTrialsOutput>;
 export {};

package/dist/tools/bio/search-patents.d.ts

@@ -0,0 +1,46 @@
+/**
+ * search_patents — patents from Amass PatentCore behind one `action`
+ * discriminator: a search that returns no claims and no description, and the
+ * details of one patent, with the claims and the description on request.
+ *
+ * The input is a flat object with an `action` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs a
+ * top-level `"type":"object"`).
+ */
+import { type PatentRecord, type PatentSummary } from "../lib/amass-client.js";
+type PatentsOutput = {
+    patents: PatentSummary[];
+} | {
+    status: "found";
+    patent: PatentRecord;
+} | {
+    status: "not_found";
+} | {
+    status: "ambiguous";
+    candidates: string[];
+};
+export declare function createSearchPatentsTool(deps: {
+    apiKey: string;
+}): import("../define-tool.js").Tool<{
+    action: "search" | "details";
+    limit: number;
+    includeClaims: boolean;
+    includeDescription: boolean;
+    query?: string | undefined;
+    assignee?: string[] | undefined;
+    inventor?: string | undefined;
+    cpcCodes?: string[] | undefined;
+    countryCode?: string[] | undefined;
+    minPublicationDate?: string | undefined;
+    maxPublicationDate?: string | undefined;
+    minFilingDate?: string | undefined;
+    maxFilingDate?: string | undefined;
+    minPriorityDate?: string | undefined;
+    maxPriorityDate?: string | undefined;
+    minGrantDate?: string | undefined;
+    maxGrantDate?: string | undefined;
+    amassId?: string | undefined;
+    publicationNumber?: string | undefined;
+    applicationNumber?: string | undefined;
+}, PatentsOutput>;
+export {};

package/dist/tools/bio/search-patents.js

@@ -0,0 +1,134 @@
+/**
+ * search_patents — patents from Amass PatentCore behind one `action`
+ * discriminator: a search that returns no claims and no description, and the
+ * details of one patent, with the claims and the description on request.
+ *
+ * The input is a flat object with an `action` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs a
+ * top-level `"type":"object"`).
+ */
+import { err, ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { describeAmassError, getPatentRecord, lookupPatentIds, searchPatentRecords, } from "../lib/amass-client.js";
+import { getAmassHeaders } from "../lib/amass-config.js";
+/** The largest `limit` that still costs one search price (5 credits for each 20 records). */
+const MAX_LIMIT = 20;
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const IDENTIFIER_FIELDS = ["amassId", "publicationNumber", "applicationNumber"];
+function dateField(description) {
+    return z.string().regex(ISO_DATE).optional().describe(`'search' only. ${description}, YYYY-MM-DD.`);
+}
+const inputSchema = z
+    .object({
+    action: z
+        .enum(["search", "details"])
+        .default("search")
+        .describe("'search' (default) — find patents with `query`. 'details' — read one patent by ONE identifier."),
+    query: z
+        .string()
+        .optional()
+        .describe("Required for 'search'. Keywords matched over the title, the abstract, the claims and the description: a compound, a target, a " +
+        "method or a formulation ('imatinib mesylate crystal form', 'KRAS G12C inhibitor')."),
+    assignee: z.array(z.string()).optional().describe("'search' only. Keep the patents of any of these assignees, e.g. ['Novartis']."),
+    inventor: z.string().optional().describe("'search' only. Keep the patents of this inventor name."),
+    cpcCodes: z.array(z.string()).optional().describe("'search' only. Keep these Cooperative Patent Classification codes, e.g. ['A61K', 'C07D']."),
+    countryCode: z.array(z.string()).optional().describe("'search' only. Keep these jurisdictions, e.g. ['US', 'EP', 'WO']."),
+    minPublicationDate: dateField("Earliest publication date"),
+    maxPublicationDate: dateField("Latest publication date"),
+    minFilingDate: dateField("Earliest filing date"),
+    maxFilingDate: dateField("Latest filing date"),
+    minPriorityDate: dateField("Earliest priority date — the effective date of the invention, the one for prior art"),
+    maxPriorityDate: dateField("Latest priority date"),
+    minGrantDate: dateField("Earliest grant date (drops each patent that was never granted)"),
+    maxGrantDate: dateField("Latest grant date"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_LIMIT)
+        .default(10)
+        .describe(`'search' only. Max patents to return (default 10, max ${MAX_LIMIT}). There are no pages: narrow with the filters.`),
+    amassId: z.string().optional().describe("'details' only. The Amass ID of one patent ('AMPC_…'), as a search returns it."),
+    publicationNumber: z.string().optional().describe("'details' only. A publication number, e.g. 'US-10266485-B2'."),
+    applicationNumber: z.string().optional().describe("'details' only. An application number; it can match more than one publication."),
+    includeClaims: z.boolean().default(false).describe("'details' only. Add the full claims text. It can run to tens of thousands of characters."),
+    includeDescription: z
+        .boolean()
+        .default(false)
+        .describe("'details' only. Add the full description text. It is often longer than the claims; ask for it only when you must read it."),
+})
+    .refine((d) => d.action !== "search" || (d.query !== undefined && d.query.trim().length > 0), {
+    message: "query is required when action is 'search'.",
+    path: ["query"],
+})
+    .refine((d) => d.action !== "details" || IDENTIFIER_FIELDS.filter((field) => d[field] !== undefined).length === 1, {
+    message: "action 'details' takes exactly one of amassId, publicationNumber, and applicationNumber.",
+    path: ["action"],
+});
+/** A request that Amass rejected as invalid is the caller's to repair; every other failure is terminal. */
+function failure(e) {
+    if (e.type === "invalid_input")
+        return err({ error: describeAmassError(e), retryable: false, cause: e });
+    throw new Error(describeAmassError(e));
+}
+export function createSearchPatentsTool(deps) {
+    return defineTool({
+        id: "search_patents",
+        description: "Patents from Amass PatentCore, across the patent offices (US, EP, WO, CN, JP, …), with one member for each patent family: the " +
+            "title, the abstract, the assignees, the inventors, the CPC codes, the priority, filing, publication and grant dates, and the citation " +
+            "counts. Answers 'who patented this compound, target or method, and when?' and 'what does this patent claim?'.\n" +
+            "action 'search' (the default) returns patents with no claims and no description. action 'details' takes ONE identifier and returns " +
+            "the patent with its family members; set includeClaims or includeDescription for the full text.\n" +
+            "ACCEPTED IDENTIFIERS for 'details': amassId ('AMPC_…'), publicationNumber ('US-10266485-B2') or applicationNumber.\n" +
+            "status 'not_found' is a valid no-data answer and status 'ambiguous' lists the candidate amassIds of an application number that " +
+            "matches more than one publication — call 'details' again with one of them. An empty search is also valid no-data. Do not retry any " +
+            "of these unchanged.\n" +
+            "Requires AMASS_API_KEY — a missing key fails terminally: do NOT retry, tell the user the key needs configuring and proceed without " +
+            "Amass patent data. Every call spends the user's Amass credits.",
+        inputSchema,
+        describeCall: "none",
+        execute: async (input) => {
+            const headers = getAmassHeaders(deps.apiKey);
+            if (input.action === "search") {
+                const patents = await searchPatentRecords({
+                    query: input.query,
+                    limit: input.limit,
+                    ...(input.assignee ? { assignee: input.assignee } : {}),
+                    ...(input.inventor ? { inventor: input.inventor } : {}),
+                    ...(input.cpcCodes ? { cpcCodes: input.cpcCodes } : {}),
+                    ...(input.countryCode ? { countryCode: input.countryCode } : {}),
+                    ...(input.minPublicationDate ? { minPublicationDate: input.minPublicationDate } : {}),
+                    ...(input.maxPublicationDate ? { maxPublicationDate: input.maxPublicationDate } : {}),
+                    ...(input.minFilingDate ? { minFilingDate: input.minFilingDate } : {}),
+                    ...(input.maxFilingDate ? { maxFilingDate: input.maxFilingDate } : {}),
+                    ...(input.minPriorityDate ? { minPriorityDate: input.minPriorityDate } : {}),
+                    ...(input.maxPriorityDate ? { maxPriorityDate: input.maxPriorityDate } : {}),
+                    ...(input.minGrantDate ? { minGrantDate: input.minGrantDate } : {}),
+                    ...(input.maxGrantDate ? { maxGrantDate: input.maxGrantDate } : {}),
+                }, headers);
+                if (patents.isErr())
+                    return failure(patents.error);
+                return ok({ patents: patents.value });
+            }
+            let amassId = input.amassId;
+            if (amassId === undefined) {
+                const ids = await lookupPatentIds({
+                    ...(input.publicationNumber === undefined ? {} : { publicationNumber: input.publicationNumber }),
+                    ...(input.applicationNumber === undefined ? {} : { applicationNumber: input.applicationNumber }),
+                }, headers);
+                if (ids.isErr())
+                    return failure(ids.error);
+                if (ids.value.length === 0)
+                    return ok({ status: "not_found" });
+                if (ids.value.length > 1)
+                    return ok({ status: "ambiguous", candidates: ids.value });
+                amassId = ids.value[0];
+            }
+            const patent = await getPatentRecord(amassId, { claims: input.includeClaims, description: input.includeDescription }, headers);
+            if (patent.isErr())
+                return failure(patent.error);
+            return ok(patent.value ? { status: "found", patent: patent.value } : { status: "not_found" });
+        },
+    });
+}

package/dist/tools/bio/search-regulatory-approvals.d.ts

@@ -0,0 +1,49 @@
+/**
+ * search_regulatory_approvals — the FDA and EMA drug authorizations of Amass
+ * RegulatoryCore, with the parsed sections of their labels, reviews, SmPCs and
+ * EPARs, behind one `action` discriminator.
+ *
+ * The three actions read the text in three sizes: `search` gives the matched
+ * excerpts, `details` the table of contents, and `section` the full text of one
+ * section. Thus an agent reads only the section that it cites.
+ *
+ * The input is a flat object with an `action` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs a
+ * top-level `"type":"object"`).
+ */
+import { type AuthorizationRecord, type AuthorizationSearchRow, type RegulatorySection } from "../lib/amass-client.js";
+type RegulatoryApprovalsOutput = {
+    authorizations: AuthorizationSearchRow[];
+} | {
+    status: "found";
+    authorization: AuthorizationRecord;
+} | {
+    status: "found";
+    section: RegulatorySection;
+} | {
+    status: "not_found";
+} | {
+    status: "ambiguous";
+    candidates: string[];
+};
+export declare function createSearchRegulatoryApprovalsTool(deps: {
+    apiKey: string;
+}): import("../define-tool.js").Tool<{
+    action: "search" | "details" | "section";
+    limit: number;
+    query?: string | undefined;
+    agency?: ("FDA" | "EMA")[] | undefined;
+    authorizationStatus?: ("UNKNOWN" | "ACTIVE" | "APPROVED_NOT_MARKETED" | "CONDITIONAL" | "SUSPENDED" | "WITHDRAWN_VOLUNTARY" | "WITHDRAWN_FORCED" | "REVOKED" | "LAPSED_SUNSET" | "REFUSED" | "WITHDRAWN_DURING_REVIEW" | "EXPIRED")[] | undefined;
+    moleculeType?: ("UNKNOWN" | "SMALL_MOLECULE" | "ANTIBODY" | "PROTEIN" | "ENZYME" | "OLIGONUCLEOTIDE" | "GENE" | "CELL" | "ANTIBODY_DRUG_CONJUGATE" | "VACCINE_COMPONENT" | "VACCINE" | "OLIGOSACCHARIDE")[] | undefined;
+    hasDesignation?: ("PRIORITY_REVIEW" | "BREAKTHROUGH_THERAPY" | "FAST_TRACK" | "RMAT" | "ACCELERATED_APPROVAL" | "ACCELERATED_ASSESSMENT" | "PRIME" | "CONDITIONAL_MA" | "EXCEPTIONAL_CIRCUMSTANCES")[] | undefined;
+    isOrphan?: boolean | undefined;
+    minAuthorizationDate?: string | undefined;
+    maxAuthorizationDate?: string | undefined;
+    amassId?: string | undefined;
+    fdaApplicationNumber?: string | undefined;
+    emaProductNumber?: string | undefined;
+    ndc?: string | undefined;
+    splSetId?: string | undefined;
+    documentSectionId?: string | undefined;
+}, RegulatoryApprovalsOutput>;
+export {};

package/dist/tools/bio/search-regulatory-approvals.js

@@ -0,0 +1,158 @@
+/**
+ * search_regulatory_approvals — the FDA and EMA drug authorizations of Amass
+ * RegulatoryCore, with the parsed sections of their labels, reviews, SmPCs and
+ * EPARs, behind one `action` discriminator.
+ *
+ * The three actions read the text in three sizes: `search` gives the matched
+ * excerpts, `details` the table of contents, and `section` the full text of one
+ * section. Thus an agent reads only the section that it cites.
+ *
+ * The input is a flat object with an `action` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs a
+ * top-level `"type":"object"`).
+ */
+import { err, ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { describeAmassError, getRegulatoryRecord, getRegulatorySection, lookupRegulatoryIds, MAX_MATCHED_SECTIONS, REGULATORY_AGENCIES, REGULATORY_AUTHORIZATION_STATUSES, REGULATORY_DESIGNATIONS, REGULATORY_MOLECULE_TYPES, searchRegulatoryRecords, } from "../lib/amass-client.js";
+import { getAmassHeaders } from "../lib/amass-config.js";
+/** The largest `limit` that still costs one search price (5 credits for each 20 records). */
+const MAX_LIMIT = 20;
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const IDENTIFIER_FIELDS = ["amassId", "fdaApplicationNumber", "emaProductNumber", "ndc", "splSetId"];
+const inputSchema = z
+    .object({
+    action: z
+        .enum(["search", "details", "section"])
+        .default("search")
+        .describe("'search' (default) — find authorizations with `query`. 'details' — read one authorization and the table of contents of its " +
+        "source documents, by ONE identifier. 'section' — read the full text of one document section, by `amassId` and `documentSectionId`."),
+    query: z
+        .string()
+        .optional()
+        .describe("Required for 'search'. Free text matched across the product metadata and the full text of the source documents: a brand or " +
+        "substance name ('Gleevec', 'imatinib'), an indication, or a label topic ('hepatotoxicity', 'QT prolongation')."),
+    agency: z.array(z.enum(REGULATORY_AGENCIES)).optional().describe("'search' only. Keep the authorizations of these agencies. Omit for both."),
+    authorizationStatus: z
+        .array(z.enum(REGULATORY_AUTHORIZATION_STATUSES))
+        .optional()
+        .describe("'search' only. Keep these authorization statuses, e.g. ['ACTIVE'] or the withdrawals. Omit for every status."),
+    moleculeType: z.array(z.enum(REGULATORY_MOLECULE_TYPES)).optional().describe("'search' only. Keep these molecule types."),
+    hasDesignation: z
+        .array(z.enum(REGULATORY_DESIGNATIONS))
+        .optional()
+        .describe("'search' only. Keep the authorizations that carry any of these designations."),
+    isOrphan: z.boolean().optional().describe("'search' only. true keeps the FDA Orphan Drug / EMA Orphan Medicine authorizations; false drops them."),
+    minAuthorizationDate: z.string().regex(ISO_DATE).optional().describe("'search' only. Earliest authorization date, YYYY-MM-DD."),
+    maxAuthorizationDate: z.string().regex(ISO_DATE).optional().describe("'search' only. Latest authorization date, YYYY-MM-DD."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_LIMIT)
+        .default(10)
+        .describe(`'search' only. Max authorizations to return (default 10, max ${MAX_LIMIT}). There are no pages: narrow with the filters.`),
+    amassId: z
+        .string()
+        .optional()
+        .describe("The Amass ID of one authorization ('AMRC_…'), as a search returns it. With 'search' it limits the full-text match to the documents " +
+        "of that one record. With 'details' it is the identifier. 'section' requires it."),
+    fdaApplicationNumber: z
+        .string()
+        .optional()
+        .describe("'details' only. An FDA application number: 'NDA021588', 'BLA125085', or the bare '021588' (each prefix is tried)."),
+    emaProductNumber: z.string().optional().describe("'details' only. An EMA product number, e.g. 'EMEA/H/C/000406'."),
+    ndc: z.string().optional().describe("'details' only. A US National Drug Code, as the product code '0078-0401' or the package code '0078-0401-05'."),
+    splSetId: z.string().optional().describe("'details' only. The Set ID of an FDA Structured Product Label."),
+    documentSectionId: z
+        .string()
+        .optional()
+        .describe("Required for 'section'. One section ID ('AMRCDS_…') from a search excerpt or from the table of contents of 'details'."),
+})
+    .refine((d) => d.action !== "search" || (d.query !== undefined && d.query.trim().length > 0), {
+    message: "query is required when action is 'search'.",
+    path: ["query"],
+})
+    .refine((d) => d.action !== "details" || IDENTIFIER_FIELDS.filter((field) => d[field] !== undefined).length === 1, {
+    message: "action 'details' takes exactly one of amassId, fdaApplicationNumber, emaProductNumber, ndc, and splSetId.",
+    path: ["action"],
+})
+    .refine((d) => d.action !== "section" || (d.amassId !== undefined && d.documentSectionId !== undefined), {
+    message: "action 'section' requires both amassId and documentSectionId.",
+    path: ["documentSectionId"],
+});
+/** A request that Amass rejected as invalid is the caller's to repair; every other failure is terminal. */
+function failure(e) {
+    if (e.type === "invalid_input")
+        return err({ error: describeAmassError(e), retryable: false, cause: e });
+    throw new Error(describeAmassError(e));
+}
+export function createSearchRegulatoryApprovalsTool(deps) {
+    return defineTool({
+        id: "search_regulatory_approvals",
+        description: "The drug authorizations of the U.S. Food and Drug Administration (FDA) and the European Medicines Agency (EMA), from Amass " +
+            "RegulatoryCore: the status, the approved indication, the marketing authorization holder, the dates, the orphan status and the " +
+            "designations (breakthrough, PRIME, accelerated approval, …), plus the full text of the source documents — FDA labels and reviews, " +
+            "EMA SmPCs and EPARs — parsed into sections. Answers 'is this drug approved, where, and for what?', 'what does its label say about X?', " +
+            "and 'which drugs carry this designation?'.\n" +
+            "action 'search' (the default) returns authorizations, each with at most " +
+            `${MAX_MATCHED_SECTIONS} matched document sections (a matchedText excerpt each) and matchedSectionCount, the true count. ` +
+            "action 'details' takes ONE identifier and returns the authorization with the FDA or EMA specifics (application number, NDCs, SmPC, " +
+            "withdrawal) and the table of contents of its documents, with no text. action 'section' returns the full text of one section. Read in " +
+            "that order: the excerpt, then the table of contents, then only the section to cite.\n" +
+            "ACCEPTED IDENTIFIERS for 'details': amassId ('AMRC_…'), fdaApplicationNumber ('NDA021588'; a bare number is tried as NDA, BLA and " +
+            "ANDA), emaProductNumber, ndc (product or package code) or splSetId.\n" +
+            "status 'not_found' is a valid no-data answer and status 'ambiguous' lists the candidate amassIds of an identifier that matches more " +
+            "than one record — call 'details' again with one of them. An empty search is also valid no-data. Do not retry any of these unchanged.\n" +
+            "Requires AMASS_API_KEY — a missing key fails terminally: do NOT retry, tell the user the key needs configuring and proceed without " +
+            "Amass regulatory data. Every call spends the user's Amass credits.",
+        inputSchema,
+        describeCall: "none",
+        execute: async (input) => {
+            const headers = getAmassHeaders(deps.apiKey);
+            if (input.action === "search") {
+                const rows = await searchRegulatoryRecords({
+                    query: input.query,
+                    limit: input.limit,
+                    ...(input.agency ? { agency: input.agency } : {}),
+                    ...(input.authorizationStatus ? { authorizationStatus: input.authorizationStatus } : {}),
+                    ...(input.moleculeType ? { moleculeType: input.moleculeType } : {}),
+                    ...(input.hasDesignation ? { hasDesignation: input.hasDesignation } : {}),
+                    ...(input.isOrphan === undefined ? {} : { isOrphan: input.isOrphan }),
+                    ...(input.minAuthorizationDate ? { minAuthorizationDate: input.minAuthorizationDate } : {}),
+                    ...(input.maxAuthorizationDate ? { maxAuthorizationDate: input.maxAuthorizationDate } : {}),
+                    ...(input.amassId ? { amassId: input.amassId } : {}),
+                }, headers);
+                if (rows.isErr())
+                    return failure(rows.error);
+                return ok({ authorizations: rows.value });
+            }
+            if (input.action === "section") {
+                const section = await getRegulatorySection(input.amassId, input.documentSectionId, headers);
+                if (section.isErr())
+                    return failure(section.error);
+                return ok(section.value ? { status: "found", section: section.value } : { status: "not_found" });
+            }
+            let amassId = input.amassId;
+            if (amassId === undefined) {
+                const ids = await lookupRegulatoryIds({
+                    ...(input.fdaApplicationNumber === undefined ? {} : { fdaApplicationNumber: input.fdaApplicationNumber }),
+                    ...(input.emaProductNumber === undefined ? {} : { emaProductNumber: input.emaProductNumber }),
+                    ...(input.ndc === undefined ? {} : { ndc: input.ndc }),
+                    ...(input.splSetId === undefined ? {} : { splSetId: input.splSetId }),
+                }, headers);
+                if (ids.isErr())
+                    return failure(ids.error);
+                if (ids.value.length === 0)
+                    return ok({ status: "not_found" });
+                if (ids.value.length > 1)
+                    return ok({ status: "ambiguous", candidates: ids.value });
+                amassId = ids.value[0];
+            }
+            const record = await getRegulatoryRecord(amassId, headers);
+            if (record.isErr())
+                return failure(record.error);
+            return ok(record.value ? { status: "found", authorization: record.value } : { status: "not_found" });
+        },
+    });
+}