@inflexa-ai/harness 0.17.0 → 0.19.0

package/dist/tools/bio/target-safety.d.ts

@@ -3,11 +3,9 @@
  * sources that carry it: the curated secondary-pharmacology panel that ships
  * with the harness, and Open Targets' curated liabilities.
  *
- * These were `check_safety_panel` and `opentargets({action:'safety'})`, and the
- * panel tool's own description instructed calling them together — a pairing
- * every caller had to remember, expressed in prose that had already gone stale
- * (it named two tools that no longer exist). Both are keyed on the same target
- * and answer the same question, so the pairing belongs in the tool.
+ * Both sources are keyed on the same target and answer the same question, so
+ * the pairing belongs in the tool rather than in prose a caller has to
+ * remember: one call consults both and merges what they carry.
  *
  * Identifier resolution is the tool's job, not the caller's: Open Targets
  * accepts ONLY an Ensembl gene id, and it is taken from the panel entry when
@@ -41,7 +39,7 @@ export declare const targetSafetyTool: import("../define-tool.js").Tool<{
     identifiers: string[];
     identifierType?: "auto" | "gene_symbol" | "uniprot" | "chembl_id" | "ensembl_id" | undefined;
     sources?: ("opentargets" | "panel")[] | undefined;
-    filterOrgan?: "hematologic" | "metabolic" | "immune" | "hepatic" | "cns" | "renal" | "respiratory" | "cardiac" | "gi" | undefined;
+    filterOrgan?: "hematologic" | "metabolic" | "immune" | "hepatic" | "musculoskeletal" | "cns" | "renal" | "reproductive" | "respiratory" | "cardiac" | "vascular" | "pns" | "gi" | "pancreas" | "endocrine_thyroid" | "dermatologic" | "ocular" | "oncology" | undefined;
     minSeverity?: "high" | "medium" | "low" | undefined;
     liabilityLimit?: number | undefined;
 }, {

package/dist/tools/bio/target-safety.js

@@ -3,11 +3,9 @@
  * sources that carry it: the curated secondary-pharmacology panel that ships
  * with the harness, and Open Targets' curated liabilities.
  *
- * These were `check_safety_panel` and `opentargets({action:'safety'})`, and the
- * panel tool's own description instructed calling them together — a pairing
- * every caller had to remember, expressed in prose that had already gone stale
- * (it named two tools that no longer exist). Both are keyed on the same target
- * and answer the same question, so the pairing belongs in the tool.
+ * Both sources are keyed on the same target and answer the same question, so
+ * the pairing belongs in the tool rather than in prose a caller has to
+ * remember: one call consults both and merges what they carry.
  *
  * Identifier resolution is the tool's job, not the caller's: Open Targets
  * accepts ONLY an Ensembl gene id, and it is taken from the panel entry when
@@ -15,7 +13,9 @@
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
-import { CHEMBL_RE, ORGAN_SYSTEMS, SEVERITIES, SafetyPanelFileSchema, UNIPROT_RE, } from "../../data/safety-panel-schema.js";
+import { ORGAN_SYSTEMS } from "../../contracts/organ-system.js";
+import { SEVERITIES } from "../../contracts/severity.js";
+import { CHEMBL_RE, SafetyPanelFileSchema, UNIPROT_RE } from "../../data/safety-panel-schema.js";
 import panelData from "../../data/safety-panel.json" with { type: "json" };
 import { defineTool } from "../define-tool.js";
 import { resolveSymbolToEnsemblId } from "../lib/ensembl-client.js";
@@ -100,6 +100,7 @@ export const targetSafetyTool = defineTool({
         "means no CURATED liability, not that none exists. Both are valid no-data — do not retry. Read `perSource` and each row's `opentargetsNote`: a " +
         "ChEMBL or UniProt identifier absent from the panel cannot be resolved to an Ensembl id, so its Open Targets half is skipped rather than empty.",
     inputSchema,
+    describeCall: "none",
     execute: async ({ identifiers, identifierType, sources, filterOrgan, minSeverity, liabilityLimit }) => {
         const selected = sources ?? [...SOURCES];
         const wantPanel = selected.includes("panel");

package/dist/tools/define-tool.d.ts

@@ -95,20 +95,28 @@ export interface ToolDefinition<Schema extends z.ZodType, Output> {
     readonly inputSchema: Schema;
     readonly executionMode?: ToolExecutionMode;
     /**
-     * One line naming what THIS call is doing — the call-time counterpart of
+     * One line that names what THIS call does — the call-time counterpart of
      * `description`. `description` self-describes the tool at attach time, so an
-     * agent knows what it holds; `describeCall` self-describes one invocation, so
+     * agent knows what it holds. `describeCall` self-describes one invocation, so
      * a surface can render four `update_working_memory` calls as four distinct
      * lines instead of four identical chips.
      *
-     * It lives here, beside `inputSchema`, because that is the one place the
-     * compiler checks the two against each other. A host-side formatter reading
-     * `input.path` by string key breaks silently the day the schema moves; this
-     * one fails to build. The tool author writes it because the tool author knows
-     * which field matters.
+     * The decision is REQUIRED. Give a hook, or give the literal `"none"`.
+     * `"none"` declares that the input of the tool cannot distinguish its calls,
+     * thus a hook can only restate the name of the tool. `defineTool` consumes
+     * the sentinel at construction, and the sentinel never reaches a packaged
+     * tool. Thus a reader of a `Tool` sees a function, or sees nothing. A hook
+     * that returns the string `"none"` is still a hook, because the discriminator
+     * is `typeof`, not equality.
      *
-     * Synchronous and pure — no I/O, no ambient state. Dispatch is what the user
-     * waits on, and a description must never be able to fail a call: the loop
+     * A hook lives here, beside `inputSchema`, because that is the one place
+     * where the compiler checks the two against each other. A host-side formatter
+     * that reads `input.path` by string key breaks silently the day the schema
+     * moves. This one fails to build. The tool author writes it, because the tool
+     * author knows which field matters.
+     *
+     * A hook is synchronous and pure — no I/O, no ambient state. Dispatch is what
+     * the user waits on, and a description must never fail a call: the loop
      * validates the input against `inputSchema` first, guards the call, and drops
      * the detail on any failure (see the tool-call-detail capability).
      *
@@ -116,10 +124,9 @@ export interface ToolDefinition<Schema extends z.ZodType, Output> {
      * removed, secrets redacted, length capped — happens once at the emit site,
      * never here.
      *
-     * OPTIONAL, and absence is a normal state: a tool without it is observable
-     * exactly as it is today. The hook never reaches the model.
+     * The hook never reaches the model.
      */
-    describeCall?(input: z.infer<Schema>): string;
+    describeCall: ((input: z.infer<Schema>) => string) | "none";
     execute(input: z.infer<Schema>, ctx: ToolContext): Promise<Result<Output, ToolError>>;
 }
 /**

package/dist/tools/define-tool.js

@@ -44,9 +44,11 @@ export function defineTool(def) {
         inputSchema: def.inputSchema,
         jsonSchema,
         executionMode,
-        // Spread rather than assigned: a tool that declares no hook carries no
+        // Spread rather than assigned: a tool that declines carries no
         // `describeCall` key at all, so "has a hook" is one property check.
-        ...(def.describeCall === undefined ? {} : { describeCall: def.describeCall }),
+        // `typeof` is the discriminator, not equality with the sentinel, so a
+        // hook that returns the string `"none"` still packages as a hook.
+        ...(typeof def.describeCall === "function" ? { describeCall: def.describeCall } : {}),
         execute: def.execute,
     };
 }

package/dist/tools/display/show-user.js

@@ -61,6 +61,7 @@ export const showUserTool = defineTool({
         "One card per call, rendered in call order; an identical repeat call resolves to the same card, so compose the " +
         "finished content before calling rather than re-rendering a draft.",
     inputSchema: ShowUserInputSchema,
+    describeCall: ({ kind, title }) => (title === undefined ? kind : `${kind}: ${title}`),
     execute: async (input, ctx) => {
         // `dataPath` is a reference the host resolves at render time; validate its
         // shape only (existence is a render-time host concern), and treat a

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,241 @@
+/**
+ * The authoring tool surface over the draft operations.
+ *
+ * The factory takes a session-state gateway, and it holds no draft. Each tool reads the thread id from the
+ * scope of the call, loads the state of that thread, applies the pure operation, and persists the new
+ * document. Thus two threads never share one draft, and a landed document outlives a host restart.
+ *
+ * Each tool maps its flat input onto a core operation, and it applies the pure operation. A landed
+ * document persists before the tool reports `applied: true`. A refused operation returns typed data in the
+ * ok channel, and the error channel stays for an unexpected failure.
+ *
+ * A call with no report thread in its scope, a thread with no stored state, and a gateway fault each
+ * refuse as typed data too. That refusal sits beside the core refusal, and it names the absent thread
+ * scope or the absent state.
+ *
+ * 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 { type Result } from "neverthrow";
+import { z } from "zod";
+import type { Scope } from "../../auth/types.js";
+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 closed set of tool-layer refusal reasons.
+ *
+ * `no-thread-scope` means that the scope of the call names no report thread. `absent-state` means that no
+ * report session exists for the thread, and it is permanent. `wrong-thread-type` means that the thread is
+ * not a report thread, and it is permanent. `scope-analysis-mismatch` means that the scope names one
+ * analysis and the thread belongs to another, and it is permanent. `stale-state` means that a concurrent
+ * turn landed first, and the agent must read the state again. `state-unavailable` means that the gateway
+ * cannot serve or store the state, and it is transient. The set is disjoint from the core
+ * `DraftRefusalReason`, thus a reader tells a core refusal from a tool-layer refusal by the reason alone.
+ */
+export type SessionRefusalReason = "no-thread-scope" | "absent-state" | "wrong-thread-type" | "scope-analysis-mismatch" | "stale-state" | "state-unavailable";
+/**
+ * A refusal that the tool layer raises before the core runs.
+ *
+ * The core refuses a bad edit. This layer refuses a call that names no thread, a thread with no stored
+ * state, or a gateway that cannot give the state. It sits beside the core `DraftRefusal`, and it never
+ * widens the closed reason set of the core.
+ */
+export interface SessionRefusal {
+    reason: SessionRefusalReason;
+    detail: string;
+}
+/**
+ * The result of a mutation tool. A refusal carries the typed reason, from the core or from the tool layer.
+ *
+ * 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 | SessionRefusal;
+};
+/** The result of `read_outline`. A load that gives no state refuses instead of an outline. */
+export type OutlineResult = {
+    outline: OutlineEntry[];
+} | {
+    refused: SessionRefusal;
+};
+/**
+ * The result of `read_block`. An absent block is an expected outcome, thus it stays in the ok channel. A
+ * load that gives no state refuses instead of a block.
+ */
+export type ReadBlockResult = {
+    found: true;
+    block: ReadableBlock;
+} | {
+    found: false;
+} | {
+    refused: SessionRefusal;
+};
+/** The result of `finish_draft`. A load that gives no state refuses instead of a finish outcome. */
+export type FinishToolResult = FinishResult | {
+    refused: SessionRefusal;
+};
+/** The state of one report thread: the document under composition, and the frozen snapshot. */
+export interface ReportSessionState {
+    readonly document: DraftDocument;
+    readonly snapshot: ReportSnapshot;
+}
+/**
+ * The concurrency token that a load hands out and a persist compares against. It is the prior document
+ * that the load read, or `null` before the first document lands. The persist lands only when the row still
+ * holds it, thus a concurrent turn that landed first turns the next persist into a conflict.
+ */
+export type SessionStateToken = DraftDocument | null;
+/**
+ * The outcome of a gateway load. `found` carries the state, the analysis that owns the thread, and the
+ * concurrency token. `absent` and `wrong-type` are permanent conditions, and `failed` is a transient fault
+ * that names its cause.
+ */
+export type SessionStateLoad = {
+    outcome: "found";
+    state: ReportSessionState;
+    analysisId: string;
+    token: SessionStateToken;
+} | {
+    outcome: "absent";
+} | {
+    outcome: "wrong-type";
+    detail: string;
+} | {
+    outcome: "failed";
+    detail: string;
+};
+/** The outcome of a gateway persist. `conflict` means that a concurrent turn landed first. */
+export type SessionStatePersist = {
+    outcome: "persisted";
+} | {
+    outcome: "conflict";
+} | {
+    outcome: "failed";
+    detail: string;
+};
+/**
+ * The session-state gateway that the tools read and write.
+ *
+ * The tool layer is the one consumer, thus the interface lives here. The interface speaks a plain
+ * discriminated value, not a `Result`, because the tools read the outcome as data. The runtime realizes
+ * the gateway over the durable store. A load gives the state, a typed absence, or a typed failure. A
+ * persist gives success, or a typed failure.
+ */
+export interface ReportSessionStateGateway {
+    load(threadId: string): Promise<SessionStateLoad>;
+    persist(threadId: string, document: DraftDocument, expected: SessionStateToken): Promise<SessionStatePersist>;
+}
+/** The thread of a call, its analysis, the loaded state, and the concurrency token that the persist compares against. */
+export interface OpenedThread {
+    readonly threadId: string;
+    readonly analysisId: string;
+    readonly state: ReportSessionState;
+    readonly token: SessionStateToken;
+}
+/**
+ * Resolve the report thread of a call, and load its state through the gateway.
+ *
+ * The report thread and its analysis ride on the analysis scope. The thread id becomes one segment of a
+ * session directory, thus the safe-id check sits here beside the shape check: a scope whose id carries a
+ * separator or a traversal segment names no thread that a tool can write under.
+ *
+ * The stored analysis of the thread must match the scope. A mismatch reads one analysis's draft and writes
+ * into another analysis's workspace, thus the resolution refuses it with a permanent reason that names the
+ * two ids. A scope of a different kind, an unsafe id, an absent thread, a wrong thread type, and a gateway
+ * fault each refuse as a typed `SessionRefusal` too.
+ *
+ * The authoring tools and the preview tool share this one resolution, thus the two surfaces accept the
+ * same thread id and map a load outcome onto a refusal the same way.
+ */
+export declare function openReportThread(gateway: ReportSessionStateGateway, scope: Scope): Promise<Result<OpenedThread, SessionRefusal>>;
+/** The eight authoring tools. */
+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, FinishToolResult>;
+}
+/**
+ * Make the eight authoring tools over a session-state gateway.
+ *
+ * Each tool reads the thread id from the scope of the call, and it loads the state of that thread through
+ * the gateway. Thus one factory serves every thread, and two threads never share one draft. A mutation
+ * persists the new document before it reports `applied: true`, thus a reported landing is never lost.
+ */
+export declare function createReportAuthoringTools(gateway: ReportSessionStateGateway): ReportAuthoringTools;
+export {};