@inflexa-ai/harness 0.16.0 → 0.17.0

package/dist/runtime/assemble.d.ts

@@ -14,14 +14,18 @@
  * `applicationVersion` stamp because all registration happens in this one call,
  * before launch — a blue/green drain treats them as a single cohort.
  */
+import { type Result } from "neverthrow";
 import { type ConversationAgentDeps } from "../agents/conversation-agent.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ResourcePolicy } from "../config/resource-limits.js";
 import type { AgentDefinition } from "../loop/types.js";
+import type { ThreadType } from "../memory/thread-store.js";
 import { type ExecuteAnalysisDeps, type ExecuteAnalysisInput, type ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
 import { type SandboxStepDeps, type SandboxStepInput, type SandboxStepResult } from "../workflows/sandbox-step.js";
 import { type ExecuteTargetAssessmentDeps, type ExecuteTargetAssessmentInput, type ExecuteTargetAssessmentResult } from "../workflows/execute-target-assessment.js";
 import { type DataProfileDeps, type DataProfileWorkflowInput } from "../tasks/data-profile.js";
+import { type CitationResolverConfig } from "../citations/resolve.js";
+import type { CitationResolver } from "../citations/types.js";
 /** Registered child sandbox-step callable the parent's child dispatch closes over. */
 export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxStepResult>;
 /**
@@ -38,8 +42,8 @@ export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxSt
  * conversation side.
  */
 export interface CoreWorkflowDeps {
-    readonly sandboxStep: Omit<SandboxStepDeps, "usageRecorder">;
-    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => Omit<ExecuteAnalysisDeps, "usageRecorder">;
+    readonly sandboxStep: Omit<SandboxStepDeps, "usageRecorder" | "citationResolver">;
+    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => Omit<ExecuteAnalysisDeps, "usageRecorder" | "citationResolver">;
     readonly executeTargetAssessment: Omit<ExecuteTargetAssessmentDeps, "usageRecorder">;
     readonly dataProfile: Omit<DataProfileDeps, "usageRecorder">;
 }
@@ -56,7 +60,7 @@ export interface RegisteredWorkflows {
  * cannot wire a stale callable, a policy that diverges from the one the
  * workflows see, or a recorder that only half the agent tree reports to.
  */
-export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy" | "usageRecorder">;
+export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy" | "usageRecorder" | "citationResolver">;
 export interface CoreRuntimeDeps {
     readonly conversation: ConversationAssemblyDeps;
     readonly workflows: CoreWorkflowDeps;
@@ -72,9 +76,51 @@ export interface CoreRuntimeDeps {
      * `createNoopUsageRecorder()`.
      */
     readonly usageRecorder?: UsageRecorder;
+    /** Harness-owned citation capability configuration; no ambient lookup occurs. */
+    readonly citationResolverConfig?: CitationResolverConfig;
 }
+/**
+ * The refusal a thread type carries no agent yet. `report` is a valid
+ * `ThreadType` with no registered agent until its builder plugs in at assembly,
+ * so resolution has to have a typed way to say "not that one" without throwing.
+ * The channel is permanent, not interim: `ThreadType` grows over the product's
+ * life, and a bare-`AgentDefinition` return would force every future member to
+ * register an agent in the same commit that adds the member.
+ */
+export interface UnregisteredThreadType {
+    readonly type: "unregistered_thread_type";
+    readonly threadType: ThreadType;
+}
+/**
+ * How a thread's type selects the agent that runs its turns. Resolution is a
+ * synchronous record lookup, so the channel is plain `Result`, never
+ * `ResultAsync`: a registered type resolves to its assembled singleton, an
+ * unregistered one refuses on the error channel.
+ */
+export interface ThreadAgentResolver {
+    forThread(type: ThreadType): Result<AgentDefinition, UnregisteredThreadType>;
+}
+/**
+ * Wrap a type→agent registry as the resolution surface. Held apart from
+ * `assembleCoreRuntime` so the resolution contract — a registered type resolves
+ * to the very object the registry holds, an unregistered one refuses — is
+ * exercisable without the DBOS registration `assembleCoreRuntime` performs.
+ *
+ * The registry holds assembled singletons, so `forThread` returns the same
+ * `AgentDefinition` object on every call for a given type: construction-time
+ * captures (an embedder's delegating provider handles, closure-wired tools)
+ * stay valid across every turn.
+ */
+export declare function createThreadAgentResolver(registry: Partial<Record<ThreadType, AgentDefinition>>): ThreadAgentResolver;
 export interface CoreRuntime {
-    readonly conversationAgent: AgentDefinition;
+    /**
+     * Thread→agent resolution — the only way to reach an assembled agent by
+     * thread type. Holds the singletons this call built; `conversation` resolves
+     * to the assembled conversation agent, every not-yet-registered type refuses
+     * on the `Result` channel.
+     */
+    readonly agents: ThreadAgentResolver;
     readonly workflows: RegisteredWorkflows;
+    readonly citationResolver: CitationResolver;
 }
 export declare function assembleCoreRuntime(deps: CoreRuntimeDeps): CoreRuntime;

package/dist/runtime/assemble.js

@@ -14,17 +14,50 @@
  * `applicationVersion` stamp because all registration happens in this one call,
  * before launch — a blue/green drain treats them as a single cohort.
  */
+import { err, ok } from "neverthrow";
 import { createConversationAgent } from "../agents/conversation-agent.js";
 import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { registerExecuteAnalysis } from "../workflows/execute-analysis.js";
 import { registerSandboxStep } from "../workflows/sandbox-step.js";
 import { registerExecuteTargetAssessment, } from "../workflows/execute-target-assessment.js";
 import { registerDataProfileWorkflow } from "../tasks/data-profile.js";
+import { createCitationResolver } from "../citations/resolve.js";
+const _assertDomainError = true;
+/**
+ * Wrap a type→agent registry as the resolution surface. Held apart from
+ * `assembleCoreRuntime` so the resolution contract — a registered type resolves
+ * to the very object the registry holds, an unregistered one refuses — is
+ * exercisable without the DBOS registration `assembleCoreRuntime` performs.
+ *
+ * The registry holds assembled singletons, so `forThread` returns the same
+ * `AgentDefinition` object on every call for a given type: construction-time
+ * captures (an embedder's delegating provider handles, closure-wired tools)
+ * stay valid across every turn.
+ */
+export function createThreadAgentResolver(registry) {
+    return {
+        forThread: (type) => {
+            const agent = registry[type];
+            if (agent === undefined) {
+                const refusal = { type: "unregistered_thread_type", threadType: type };
+                return err(refusal);
+            }
+            return ok(agent);
+        },
+    };
+}
 export function assembleCoreRuntime(deps) {
     const { conversation, workflows: wf, resourcePolicy } = deps;
     const usageRecorder = deps.usageRecorder ?? createNoopUsageRecorder();
-    const sandboxStep = registerSandboxStep({ ...wf.sandboxStep, usageRecorder });
-    const executeAnalysis = registerExecuteAnalysis({ ...wf.buildExecuteAnalysis(sandboxStep), usageRecorder });
+    const citationResolver = createCitationResolver({
+        ...(deps.citationResolverConfig ?? {}),
+        ...(deps.citationResolverConfig?.ncbiApiKey !== undefined || conversation.bioKeys.ncbi === undefined ? {} : { ncbiApiKey: conversation.bioKeys.ncbi }),
+        ...(deps.citationResolverConfig?.semanticScholarApiKey !== undefined || conversation.bioKeys.semanticScholar === undefined
+            ? {}
+            : { semanticScholarApiKey: conversation.bioKeys.semanticScholar }),
+    });
+    const sandboxStep = registerSandboxStep({ ...wf.sandboxStep, citationResolver, usageRecorder });
+    const executeAnalysis = registerExecuteAnalysis({ ...wf.buildExecuteAnalysis(sandboxStep), citationResolver, usageRecorder });
     const executeTargetAssessment = registerExecuteTargetAssessment({ ...wf.executeTargetAssessment, usageRecorder });
     const dataProfile = registerDataProfileWorkflow({ ...wf.dataProfile, usageRecorder });
     const conversationAgent = createConversationAgent({
@@ -32,14 +65,25 @@ export function assembleCoreRuntime(deps) {
         executeAnalysisWorkflow: executeAnalysis,
         resourcePolicy,
         usageRecorder,
+        citationResolver,
     });
+    // The single registration point for every typed agent. One entry today; a
+    // future thread type's agent plugs in here at assembly with no embedder
+    // change. `conversation` is required at the type level because boot resolves
+    // it unconditionally (`boot.ts` backfill) — a dropped registration must fail
+    // tsc here, not surface only as a boot-time throw. The `Partial` over the
+    // rest keeps the compiler honest that `report` has no agent yet.
+    const agents = {
+        conversation: conversationAgent,
+    };
     return {
-        conversationAgent,
+        agents: createThreadAgentResolver(agents),
         workflows: {
             executeAnalysis,
             sandboxStep,
             executeTargetAssessment,
             dataProfile,
         },
+        citationResolver,
     };
 }

package/dist/runtime/boot.js

@@ -36,6 +36,7 @@
  * releases whatever it acquired). Only `shutdown` swallows per-step failures —
  * once shutdown starts, exiting takes precedence (see `runShutdownSequence`).
  */
+import { unwrapOrThrow } from "../lib/result.js";
 import { SANDBOX_AGENT_META } from "../agents/sandbox/index.js";
 import { validateAgentSkills } from "../agents/sandbox/validate-skills.js";
 import { initCortexState } from "../state/init.js";
@@ -54,10 +55,15 @@ export async function bootHarness(deps) {
     await initCortexState(pool);
     await assertConnectionBudget({ pool, logger, config: deps.connectionBudget });
     const runtime = assembleCoreRuntime(core);
+    // Assembly registers `conversation` unconditionally, so this resolution can
+    // never refuse; `unwrapOrThrow` turns the impossible error branch into a
+    // boot-propagating throw rather than threading a Result through the boot
+    // sequence, whose steps already fail by propagation.
+    const conversationAgent = unwrapOrThrow(runtime.agents.forThread("conversation"));
     await backfillConversationDisplayEnvelopes({
         pool,
         resolveWorkspaceRoot: core.conversation.resolveWorkspaceRoot,
-        tools: runtime.conversationAgent.tools,
+        tools: conversationAgent.tools,
     });
     await deps.beforeLaunch?.();
     await launchDbos({ config: deps.dbos, logger });

package/dist/state/init.js

@@ -275,12 +275,57 @@ CREATE TABLE IF NOT EXISTS cortex_analysis_threads (
   title       TEXT,
   created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  deleted_at  TIMESTAMPTZ
+  deleted_at  TIMESTAMPTZ,
+  thread_type TEXT NOT NULL DEFAULT 'conversation',
+  -- The cascade on this self-reference is a BACKSTOP, never the deletion path.
+  -- messages carries no foreign key to this table, so a cascade firing on its
+  -- own drops a descendant's metadata row while leaving that descendant's
+  -- messages rows behind with nothing naming them, beyond the reach of any
+  -- later thread-scoped or analysis-scoped reclamation. purgeThread therefore
+  -- walks the subtree and deletes its messages rows explicitly, to the same
+  -- depth the cascade reaches.
+  parent_thread_id TEXT REFERENCES cortex_analysis_threads(thread_id) ON DELETE CASCADE,
+  parent_seq  BIGINT
 );
 
+-- These three sit here, and not in the additive block further down, because the
+-- index below reads one of them. CREATE TABLE IF NOT EXISTS adds no column to a
+-- table that already exists, so on every database but a brand new one the column
+-- arrives from an ALTER -- and the whole additive block runs after this text. An
+-- index declared here over a column added there fails with 42703 on exactly the
+-- databases a migration exists to serve. Additive with no backfill either way: an
+-- existing row reads back as a root conversation thread with no anchor, which is
+-- what it is.
+ALTER TABLE cortex_analysis_threads
+  ADD COLUMN IF NOT EXISTS thread_type TEXT NOT NULL DEFAULT 'conversation';
+
+ALTER TABLE cortex_analysis_threads
+  ADD COLUMN IF NOT EXISTS parent_thread_id TEXT REFERENCES cortex_analysis_threads(thread_id) ON DELETE CASCADE;
+
+ALTER TABLE cortex_analysis_threads
+  ADD COLUMN IF NOT EXISTS parent_seq BIGINT;
+
 CREATE INDEX IF NOT EXISTS idx_cortex_analysis_threads_analysis
   ON cortex_analysis_threads(analysis_id) WHERE deleted_at IS NULL;
 
+-- Not partial, unlike the analysis index above. Two of the three readers of
+-- parent_thread_id carry no deleted_at predicate and cannot: the recursive
+-- subtree walk in thread-store.ts must reach archived descendants, and the
+-- referential trigger behind ON DELETE CASCADE is the database's own query.
+-- Postgres uses a partial index only where it can prove the predicate holds, so
+-- a partial index here leaves both to a sequential scan of the whole table.
+-- Over 150k rows that measured 28 ms per walk and 20 ms per cascade, against
+-- 0.06 ms and 0.10 ms with this one. The third reader, a listing filtered by
+-- parent, keeps an index scan either way.
+--
+-- The old partial index goes by name: CREATE INDEX IF NOT EXISTS keeps whatever
+-- definition already holds the name, so a database that built the partial one
+-- would never see this.
+DROP INDEX IF EXISTS idx_cortex_analysis_threads_parent;
+
+CREATE INDEX IF NOT EXISTS idx_cortex_analysis_threads_parent_fk
+  ON cortex_analysis_threads(parent_thread_id);
+
 -- Working memory — the harness WorkingMemory module's table, one row per
 -- analysis. The data column holds a JSONB object with four sections (goal,
 -- constraints, hypotheses, findings). Section updates are a read-modify-write

package/dist/state/schema.d.ts

@@ -46,10 +46,10 @@ export declare const ArtifactRowSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ArtifactRow = z.infer<typeof ArtifactRowSchema>;
 export declare const RunStatus: z.ZodEnum<{
+    partial: "partial";
     running: "running";
     completed: "completed";
     failed: "failed";
-    partial: "partial";
     canceled: "canceled";
     suspended_insufficient_funds: "suspended_insufficient_funds";
 }>;
@@ -77,10 +77,10 @@ export declare const CortexRunRowSchema: z.ZodObject<{
     threadId: z.ZodNullable<z.ZodString>;
     workflowName: z.ZodString;
     status: z.ZodEnum<{
+        partial: "partial";
         running: "running";
         completed: "completed";
         failed: "failed";
-        partial: "partial";
         canceled: "canceled";
         suspended_insufficient_funds: "suspended_insufficient_funds";
     }>;

package/dist/tools/bio/gene-preclinical-profile.d.ts

@@ -51,7 +51,7 @@ export declare const genePreclinicalProfileTool: import("../define-tool.js").Too
     geneSymbol: string;
     include?: ("expression" | "knockout")[] | undefined;
     species?: ("homo_sapiens" | "mus_musculus" | "rattus_norvegicus" | "canis_lupus_familiaris" | "macaca_mulatta")[] | undefined;
-    minRank?: "high" | "medium" | "low" | "absent" | undefined;
+    minRank?: "absent" | "high" | "medium" | "low" | undefined;
     tissueLimit?: number | undefined;
     phenotypeLimit?: number | undefined;
 }, PreclinicalOutput>;

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

@@ -13,6 +13,7 @@ export interface BioToolKeys {
     readonly epaCcte: string;
     readonly ncbi?: string;
     readonly github?: string;
+    readonly semanticScholar?: string;
 }
 /**
  * The NCBI-backed literature tool, built from the shared key slice.

package/dist/tools/bio/pubmed.js

@@ -140,16 +140,16 @@ export function createPubMedTool(deps) {
                     return `fulltext ${input.pmcId ?? ""}`;
             }
         },
-        execute: async (input) => {
+        execute: async (input, context) => {
             switch (input.action) {
                 case "search":
                     return ok(await searchPubmed(deps.ncbiApiKey, input.query, {
                         maxResults: input.maxResults ?? DEFAULTS.searchResults,
                         ...(input.sort ? { sort: input.sort } : {}),
                         ...(input.dateRange ? { dateRange: input.dateRange } : {}),
-                    }));
+                    }, context.signal));
                 case "details": {
-                    const { articles, notFound } = await getArticleDetails(deps.ncbiApiKey, input.pmids);
+                    const { articles, notFound } = await getArticleDetails(deps.ncbiApiKey, input.pmids, context.signal);
                     return ok({
                         articles: boundArticleDetails(articles, {
                             maxAuthors: input.maxAuthors ?? DEFAULTS.maxAuthors,
@@ -162,7 +162,7 @@ export function createPubMedTool(deps) {
                     const parsed = await getArticleFullText(deps.ncbiApiKey, input.pmcId, {
                         ...(input.sections ? { sections: input.sections } : {}),
                         maxChars: input.maxChars ?? DEFAULTS.maxChars,
-                    });
+                    }, context.signal);
                     // "Not open-access" is an expected outcome — a data variant, not an error.
                     if (!parsed)
                         return ok({ pmcId: input.pmcId, available: false });

package/dist/tools/lib/ncbi-utils.d.ts

@@ -1,58 +1,3 @@
-/**
- * Shared NCBI E-utilities helpers for PubMed/PMC tools.
- *
- * Provides base URL constants, API key injection, and XML-to-article
- * mapping functions for PubMed and PMC DTD structures.
- */
-export declare const NCBI_BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
-export declare const NCBI_IDCONV = "https://www.ncbi.nlm.nih.gov/pmc/utils/idconv/v1.0";
-/**
- * Append `api_key` and optional extra params to a base URL.
- * Omits the key when `apiKey` is undefined.
- */
-export declare function ncbiUrl(apiKey: string | undefined, base: string, params: Record<string, string | number | undefined>): string;
-export interface PubMedSummary {
-    pmid: string;
-    title: string;
-    journal: string;
-    year: string;
-    authors: string;
-}
-/**
- * Parse esummary XML into PubMedSummary records.
- */
-export declare function parseEsummary(xml: string): PubMedSummary[];
-export interface ArticleDetail {
-    pmid: string;
-    title: string;
-    abstract: string;
-    authors: string[];
-    journal: string;
-    year: string;
-    doi: string;
-    meshTerms: string[];
-    pmcId: string | null;
-}
-/**
- * Parse efetch PubMed XML into ArticleDetail records.
- * `pmcId` is left null here — resolved separately via ID Converter.
- */
-export declare function parseEfetch(xml: string): ArticleDetail[];
-/**
- * Parse ID Converter JSON response into a PMID → PMC ID map.
- * Returns only entries that have a PMC ID.
- */
-export declare function parseIdConvResponse(data: unknown): Map<string, string>;
-export interface ArticleSection {
-    heading: string;
-    text: string;
-}
-export interface FullTextResult {
-    fullText: string;
-    sections: ArticleSection[];
-}
-/**
- * Parse PMC efetch XML into plain text with section structure.
- * Omits figures, tables, and supplementary material markup.
- */
-export declare function parsePmcFullText(xml: string): FullTextResult | null;
+/** @deprecated Import NCBI authority contracts from literature/sources/pubmed. */
+export { NCBI_BASE, NCBI_IDCONV, ncbiUrl, parseEfetch, parseEsummary, parseIdConvResponse, parsePmcFullText } from "../../literature/sources/pubmed.js";
+export type { ArticleDetail, ArticleSection, FullTextResult, PubMedSummary } from "../../literature/sources/pubmed.js";