@inflexa-ai/harness 0.18.0 → 0.19.0

package/dist/state/report-versions.js

@@ -10,7 +10,7 @@
  * one thread trips the constraint, and the store maps that trip to the typed
  * refusal thread_already_holds_version.
  *
- * The store keeps the snapshot and the anchor as given, and it never mints a
+ * The store keeps the snapshot and the anchor as given, and it never pins a
  * snapshot. A read parses the stored document and the stored snapshot with the
  * current schemas. A row that fails a parse reads as a typed error, and it does
  * not crash. An absent row reads as a normal absence.
@@ -21,42 +21,15 @@
  */
 import { randomUUID } from "node:crypto";
 import { err, errAsync, ok } from "neverthrow";
-import { z } from "zod";
 import { ReportDocumentSchema } from "../contracts/report-blocks.js";
 import { tryMutation, tryQuery } from "../lib/db-result.js";
+import { parseSnapshot, reduceIssues } from "./snapshot-parse.js";
 /**
  * The name of the unique constraint on thread_id. Postgres reports it on a
  * duplicate-thread refusal, and the record matches it to map the trip to the
  * thread_already_holds_version refusal.
  */
 const THREAD_UNIQUE_CONSTRAINT = "cortex_report_versions_one_per_thread";
-/**
- * One pinned artifact of a stored snapshot. The value carries the content hash,
- * an optional file type, and optional rows. The `z.ZodType<ReportSnapshot>`
- * annotation below keeps this schema and the `ArtifactSnapshot` type of the
- * reference model in step, thus a change to one shows as a compile error there.
- */
-const ArtifactSnapshotSchema = z.object({
-    hash: z.string(),
-    fileType: z.string().nullable().optional(),
-    rows: z.array(z.record(z.string(), z.union([z.string(), z.number()]))).optional(),
-});
-/**
- * The stored-snapshot schema. The annotation ties the parse output to the
- * `ReportSnapshot` type of the reference model, thus the store and the structural
- * validation never disagree about the snapshot shape. The mint never fills `rows`,
- * but the schema admits what the type admits.
- */
-const ReportSnapshotSchema = z.object({
-    artifacts: z.record(z.string(), ArtifactSnapshotSchema),
-    citations: z.array(z.string()).optional(),
-});
-function reduceIssues(error) {
-    return error.issues.map((issue) => ({
-        path: issue.path.map((segment) => String(segment)).join("."),
-        message: issue.message,
-    }));
-}
 const _assertRecordError = true;
 const _assertReadError = true;
 /**
@@ -78,9 +51,9 @@ function rowToVersion(row) {
     if (!document.success) {
         return err({ type: "corrupt_version", op: "report-versions.read", versionId: row.version_id, part: "document", issues: reduceIssues(document.error) });
     }
-    const snapshot = ReportSnapshotSchema.safeParse(row.snapshot);
-    if (!snapshot.success) {
-        return err({ type: "corrupt_version", op: "report-versions.read", versionId: row.version_id, part: "snapshot", issues: reduceIssues(snapshot.error) });
+    const snapshot = parseSnapshot(row.snapshot);
+    if (snapshot.isErr()) {
+        return err({ type: "corrupt_version", op: "report-versions.read", versionId: row.version_id, part: "snapshot", issues: snapshot.error });
     }
     return ok({
         versionId: row.version_id,
@@ -90,7 +63,7 @@ function rowToVersion(row) {
         parentSeq: row.parent_seq === null ? null : Number(row.parent_seq),
         parentVersionId: row.parent_version_id,
         document: document.data,
-        snapshot: snapshot.data,
+        snapshot: snapshot.value,
         createdAt: row.created_at,
     });
 }
@@ -126,11 +99,11 @@ export function createReportVersionStore({ pool }) {
             return errAsync({ type: "malformed_document", op: "report-versions.record", issues: reduceIssues(parsed.error) });
         }
         const document = parsed.data;
-        // The parse guards the row against a caller bug through a cast. The store
-        // stores the given value, thus the parse changes no value.
-        const parsedSnapshot = ReportSnapshotSchema.safeParse(input.snapshot);
-        if (!parsedSnapshot.success) {
-            return errAsync({ type: "malformed_snapshot", op: "report-versions.record", issues: reduceIssues(parsedSnapshot.error) });
+        // The parse guards the row against a caller bug. The store stores the given
+        // value, thus the parse changes no value.
+        const parsedSnapshot = parseSnapshot(input.snapshot);
+        if (parsedSnapshot.isErr()) {
+            return errAsync({ type: "malformed_snapshot", op: "report-versions.record", issues: parsedSnapshot.error });
         }
         const insert = () => {
             const versionId = randomUUID();

package/dist/state/snapshot-parse.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The one parse of a stored report snapshot, shared by the two stores.
+ *
+ * The session-state store and the version store each hold a snapshot column, and
+ * each reads it back the same way. A path such as `__proto__` is an ordinary
+ * artifact key of the ledger, and the pin keeps it as an own member of a
+ * null-prototype map (`report-model/pin-snapshot.ts`). Each object-shaped schema
+ * of zod drops such a key, thus a store that parsed the map through one would
+ * resolve a reference to that artifact before a reload and refuse it as absent
+ * after one. The walk reads the own keys of the stored map, and it parses each
+ * value on its own, thus the two stores agree on the key set.
+ */
+import { type Result } from "neverthrow";
+import { z } from "zod";
+import type { ReportSnapshot } from "../report-model/reference-resolver.js";
+/** One reduced schema issue -- the dotted path and the message, without the rest. */
+export interface SchemaIssue {
+    readonly path: string;
+    readonly message: string;
+}
+/** Reduce a zod error to the dotted path and the message of each issue. */
+export declare function reduceIssues(error: z.ZodError): SchemaIssue[];
+/**
+ * Parse a stored snapshot.
+ *
+ * The artifacts map never goes through a zod object schema, for the reason that
+ * the module header gives: a zod object drops a `__proto__` key and the pin keeps
+ * it. The walk reads the own keys of the stored map, and it parses each value on
+ * its own.
+ *
+ * The `ReportSnapshot` return type ties this parse to the type of the reference
+ * model, thus a change to one shows as a compile error here.
+ */
+export declare function parseSnapshot(stored: unknown): Result<ReportSnapshot, SchemaIssue[]>;

package/dist/state/snapshot-parse.js

@@ -0,0 +1,82 @@
+/**
+ * The one parse of a stored report snapshot, shared by the two stores.
+ *
+ * The session-state store and the version store each hold a snapshot column, and
+ * each reads it back the same way. A path such as `__proto__` is an ordinary
+ * artifact key of the ledger, and the pin keeps it as an own member of a
+ * null-prototype map (`report-model/pin-snapshot.ts`). Each object-shaped schema
+ * of zod drops such a key, thus a store that parsed the map through one would
+ * resolve a reference to that artifact before a reload and refuse it as absent
+ * after one. The walk reads the own keys of the stored map, and it parses each
+ * value on its own, thus the two stores agree on the key set.
+ */
+import { err, ok } from "neverthrow";
+import { z } from "zod";
+/**
+ * One pinned artifact of a stored snapshot. The value carries the content hash, an
+ * optional file type, and optional rows.
+ */
+const ArtifactSnapshotSchema = z.object({
+    hash: z.string(),
+    fileType: z.string().nullable().optional(),
+    rows: z.array(z.record(z.string(), z.union([z.string(), z.number()]))).optional(),
+});
+/** The citation list of a stored snapshot. A snapshot with no list reads as an absent field. */
+const CitationsSchema = z.array(z.string()).optional();
+/** Reduce a zod error to the dotted path and the message of each issue. */
+export function reduceIssues(error) {
+    return error.issues.map((issue) => ({
+        path: issue.path.map((segment) => String(segment)).join("."),
+        message: issue.message,
+    }));
+}
+/** Put a prefix before the path of each issue, thus a nested parse names the key that failed. */
+function prefixIssues(prefix, issues) {
+    return issues.map((issue) => ({
+        path: issue.path === "" ? prefix : `${prefix}.${issue.path}`,
+        message: issue.message,
+    }));
+}
+/** A stored map is a plain object. An array and a null carry no own key that a map read can use. */
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Parse a stored snapshot.
+ *
+ * The artifacts map never goes through a zod object schema, for the reason that
+ * the module header gives: a zod object drops a `__proto__` key and the pin keeps
+ * it. The walk reads the own keys of the stored map, and it parses each value on
+ * its own.
+ *
+ * The `ReportSnapshot` return type ties this parse to the type of the reference
+ * model, thus a change to one shows as a compile error here.
+ */
+export function parseSnapshot(stored) {
+    if (!isPlainRecord(stored)) {
+        return err([{ path: "", message: "the stored snapshot is not an object" }]);
+    }
+    if (!isPlainRecord(stored.artifacts)) {
+        return err([{ path: "artifacts", message: "the artifacts map is not an object" }]);
+    }
+    const citations = CitationsSchema.safeParse(stored.citations);
+    if (!citations.success) {
+        return err(prefixIssues("citations", reduceIssues(citations.error)));
+    }
+    // The map takes a null prototype, the same as the pin, thus a path such as
+    // `__proto__` stays an ordinary entry and never reaches a prototype slot.
+    const artifacts = Object.create(null);
+    const issues = [];
+    for (const [path, value] of Object.entries(stored.artifacts)) {
+        const parsed = ArtifactSnapshotSchema.safeParse(value);
+        if (!parsed.success) {
+            issues.push(...prefixIssues(`artifacts.${path}`, reduceIssues(parsed.error)));
+            continue;
+        }
+        artifacts[path] = parsed.data;
+    }
+    if (issues.length > 0) {
+        return err(issues);
+    }
+    return citations.data === undefined ? ok({ artifacts }) : ok({ artifacts, citations: citations.data });
+}

package/dist/tools/ad-hoc-router.d.ts

@@ -2,7 +2,7 @@ import type { Pool } from "pg";
 import { type AgentSession } from "../auth/types.js";
 import type { ResourcePolicy, ResourceSpec } from "../config/resource-limits.js";
 import type { Logger } from "../lib/logger.js";
-import type { ChatProvider } from "../providers/types.js";
+import { type ChatProvider } from "../providers/types.js";
 export declare const AD_HOC_ROUTER_AGENT_ID = "adhoc-router";
 export declare const AD_HOC_ROUTER_TIMEOUT_MS = 10000;
 export declare const AD_HOC_FALLBACK_AGENT_ID = "scientific-executor";
@@ -18,7 +18,12 @@ export interface AdHocRouterDeps {
     readonly pool: Pool;
     readonly resourcePolicy?: ResourcePolicy;
     readonly logger?: Logger;
-    /** Test seam; production always uses {@link AD_HOC_ROUTER_TIMEOUT_MS}. */
+    /**
+     * Test seam that sets an explicit deadline. An explicit value overrides the
+     * derived deadline. The derived deadline is the maximum of
+     * {@link AD_HOC_ROUTER_TIMEOUT_MS} and the request-timeout limit that the
+     * provider advertises.
+     */
     readonly timeoutMs?: number;
 }
 export declare function defaultAdHocResources(policy?: ResourcePolicy): ResourceSpec;

package/dist/tools/ad-hoc-router.js

@@ -6,6 +6,7 @@ import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from
 import { createNoopLogger } from "../lib/console-logger.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { resourceEstimationSection } from "../prompts/planner.js";
+import { effectiveDeadlineMs } from "../providers/types.js";
 import { loadDataProfileStatus } from "../state/index.js";
 export const AD_HOC_ROUTER_AGENT_ID = "adhoc-router";
 export const AD_HOC_ROUTER_TIMEOUT_MS = 10_000;
@@ -72,7 +73,7 @@ export async function routeAdHocRequest(deps, input) {
     const catalog = PLANNABLE_AGENT_CATALOG.map((agent) => `- ${agent.id}: capabilities [${agent.capabilities.join(", ")}]; suitable for [${agent.suitableFor.join(", ")}]`).join("\n");
     const orientation = await profileOrientation(deps.pool, input.analysisId, logger);
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(new Error("ad hoc routing timed out")), deps.timeoutMs ?? AD_HOC_ROUTER_TIMEOUT_MS);
+    const timer = setTimeout(() => controller.abort(new Error("ad hoc routing timed out")), effectiveDeadlineMs(deps.provider, AD_HOC_ROUTER_TIMEOUT_MS, deps.timeoutMs));
     const signal = AbortSignal.any([input.signal, controller.signal]);
     let raw;
     let failure;

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

@@ -1,18 +1,24 @@
 /**
  * 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.
+ * 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. 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.
+ * 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";
@@ -77,7 +83,30 @@ export interface ChangedContainer {
     children: OutlineEntry[];
 }
 /**
- * The result of a mutation tool. A refusal carries the typed reason.
+ * 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
@@ -92,26 +121,105 @@ export type MutationResult = {
     changed: ChangedContainer[];
 } | {
     applied: false;
-    refusal: DraftRefusal;
+    refusal: DraftRefusal | SessionRefusal;
 };
-/** The result of `read_outline`. */
-export interface OutlineResult {
+/** The result of `read_outline`. A load that gives no state refuses instead of an outline. */
+export type OutlineResult = {
     outline: OutlineEntry[];
-}
-/** The result of `read_block`. An absent block is an expected outcome, thus it stays in the ok channel. */
+} | {
+    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 state that the factory closes over. */
-export interface ReportAuthoringState {
+/** 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 draft to start from. The default is an empty draft. */
-    readonly initialDraft?: DraftDocument;
 }
-/** The eight authoring tools, plus a read of the current draft. */
+/**
+ * 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>;
@@ -120,15 +228,14 @@ export interface ReportAuthoringTools {
     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;
+    readonly finish_draft: Tool<FinishDraftInput, FinishToolResult>;
 }
 /**
- * Make the eight authoring tools over one draft.
+ * Make the eight authoring tools over a session-state gateway.
  *
- * 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.
+ * 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(state: ReportAuthoringState): ReportAuthoringTools;
+export declare function createReportAuthoringTools(gateway: ReportSessionStateGateway): ReportAuthoringTools;
 export {};