@inflexa-ai/harness 0.18.0 → 0.19.0

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

@@ -1,19 +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 { err, ok } from "neverthrow";
 import { z } from "zod";
+import { isSafeId } from "../../workspace/paths.js";
 import { addBlock, changeBlock, locate, moveBlock, removeBlock, setTitle, } from "../../report-model/draft-operations.js";
 import { buildOutline, childOutline, readBlock } from "../../report-model/draft-read.js";
 import { finishDraft } from "../../report-model/draft-finish.js";
@@ -78,6 +83,44 @@ const setTitleInput = z.object({
     title: z.string().min(1),
 });
 const finishDraftInput = z.object({});
+/**
+ * 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 async function openReportThread(gateway, scope) {
+    if (scope.kind !== "analysis" || scope.threadId === undefined || !isSafeId(scope.threadId)) {
+        return err({ reason: "no-thread-scope", detail: "the scope of the call names no usable report thread id" });
+    }
+    const { threadId, analysisId } = scope;
+    const loaded = await gateway.load(threadId);
+    if (loaded.outcome === "absent") {
+        return err({ reason: "absent-state", detail: `no report session exists for the thread ${threadId}, and this condition is permanent` });
+    }
+    if (loaded.outcome === "wrong-type") {
+        return err({ reason: "wrong-thread-type", detail: `${loaded.detail}, and this condition is permanent` });
+    }
+    if (loaded.outcome === "failed") {
+        return err({ reason: "state-unavailable", detail: loaded.detail });
+    }
+    if (loaded.analysisId !== analysisId) {
+        return err({
+            reason: "scope-analysis-mismatch",
+            detail: `the scope names the analysis ${analysisId}, but the thread ${threadId} belongs to the analysis ${loaded.analysisId}`,
+        });
+    }
+    return ok({ threadId, analysisId, state: loaded.state, token: loaded.token });
+}
 /** Read an absentable field. An explicit `null` and an omitted key both mean that the model gave no value. */
 function given(value) {
     return value ?? undefined;
@@ -197,37 +240,59 @@ function containerIn(document, parentId) {
 /**
  * Every tool of this surface runs inline.
  *
- * The draft is closure memory with no durable backing. A step-mode tool goes through `DBOS.runStep`, which
- * caches the result of a step and replays it without running the body. A replay after a host restart would
- * hand the agent the cached `applied: true` outline of each landed operation while the rebuilt closure
- * holds an empty draft, and the finish would then report an empty document for a report that the
- * transcript shows as complete. Inline mode keeps the tool result and the draft in one lifetime.
+ * A tool loads the state of its thread, applies the pure operation, and persists the result in one body.
+ * The reported outline must agree with the row that the body just wrote. A step-mode tool goes through
+ * `DBOS.runStep`, which caches the result of a step and replays it without a fresh load. A replay could
+ * then report an outline that the current row no longer holds. Inline mode reads and writes the row in one
+ * lifetime, thus the outline never drifts from the state.
  */
 const AUTHORING_EXECUTION_MODE = "inline";
 /**
- * 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 function createReportAuthoringTools(state) {
-    const snapshot = state.snapshot;
-    let draft = state.initialDraft ?? { title: "", sections: [] };
+export function createReportAuthoringTools(gateway) {
+    /**
+     * Resolve the thread of the call, and load its state.
+     *
+     * The shared `openReportThread` holds the one resolution. A scope of a different kind, an unsafe or
+     * absent thread id, an absent row, and a gateway fault each refuse before the call reaches a core
+     * operation.
+     */
+    const openThread = (ctx) => openReportThread(gateway, ctx.session.scope);
     /**
-     * Swap the holder on a landing, and report the containers that the operation changed.
+     * Persist a landing, and report the containers that the operation changed.
      *
-     * `holders` names them by id, and it reads the draft as it was and the draft as it becomes, because a
-     * removed block has a holder only in the first and an added block has one only in the second. The
-     * child order comes out of `next` in either case.
+     * `holders` names them by id, and it reads the previous document and the next document, because a
+     * removed block has a holder only in the first and an added block has one only in the second. The child
+     * order comes out of `next` in either case. A persist fault refuses with `state-unavailable`, thus the
+     * tool reports `applied: true` only after the row holds the new document.
+     *
+     * The persist is a compare-and-swap against the token that the load read. A concurrent turn that landed
+     * first turns the persist into a conflict, and the tool refuses with `stale-state`.
      */
-    const land = (result, holders) => result.match((next) => {
-        const previous = draft;
-        draft = next;
+    const land = async (threadId, token, previous, result, holders) => {
+        if (result.isErr()) {
+            return { applied: false, refusal: result.error };
+        }
+        const next = result.value;
+        const persisted = await gateway.persist(threadId, next, token);
+        if (persisted.outcome === "conflict") {
+            return {
+                applied: false,
+                refusal: { reason: "stale-state", detail: "another turn changed the report since this turn read it, thus read the state again" },
+            };
+        }
+        if (persisted.outcome === "failed") {
+            return { applied: false, refusal: { reason: "state-unavailable", detail: persisted.detail } };
+        }
         // A move inside one container names the same holder two times.
         const unique = [...new Set(holders(previous, next))];
         return { applied: true, changed: unique.map((parentId) => containerIn(next, parentId)) };
-    }, (refusal) => ({ applied: false, refusal }));
+    };
     const refuse = (refusal) => ({ applied: false, refusal });
     const add_block = defineTool({
         id: "add_block",
@@ -241,16 +306,19 @@ export function createReportAuthoringTools(state) {
             const kind = readKind(decodeBlockPayload(input.block));
             return kind !== undefined ? `add ${kind}` : "add a block";
         },
-        execute: async (input) => {
+        execute: async (input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok(refuse(opened.error));
+            }
+            const { threadId, state, token } = opened.value;
             const destination = toDestination(input);
             if (destination.isErr()) {
                 return ok(refuse(destination.error));
             }
             const block = decodeBlockPayload(input.block);
             const addedId = readId(block);
-            return ok(land(addBlock(draft, { block, destination: destination.value }, snapshot), (_previous, next) => [
-                addedId === undefined ? undefined : holderIdOf(next, addedId),
-            ]));
+            return ok(await land(threadId, token, state.document, addBlock(state.document, { block, destination: destination.value }, state.snapshot), (_previous, next) => [addedId === undefined ? undefined : holderIdOf(next, addedId)]));
         },
     });
     const change_block = defineTool({
@@ -260,12 +328,19 @@ export function createReportAuthoringTools(state) {
         inputSchema: changeBlockInput,
         executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `change ${input.targetId}`,
-        execute: async (input) => {
+        execute: async (input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok(refuse(opened.error));
+            }
+            const { threadId, state, token } = opened.value;
             const operation = toChangeOperation(input);
             if (operation.isErr()) {
                 return ok(refuse(operation.error));
             }
-            return ok(land(changeBlock(draft, operation.value, snapshot), (_previous, next) => [holderIdOf(next, input.targetId)]));
+            return ok(await land(threadId, token, state.document, changeBlock(state.document, operation.value, state.snapshot), (_previous, next) => [
+                holderIdOf(next, input.targetId),
+            ]));
         },
     });
     const remove_block = defineTool({
@@ -274,7 +349,16 @@ export function createReportAuthoringTools(state) {
         inputSchema: removeBlockInput,
         executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `remove ${input.targetId}`,
-        execute: async (input) => ok(land(removeBlock(draft, { targetId: input.targetId }, snapshot), (previous) => [holderIdOf(previous, input.targetId)])),
+        execute: async (input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok(refuse(opened.error));
+            }
+            const { threadId, state, token } = opened.value;
+            return ok(await land(threadId, token, state.document, removeBlock(state.document, { targetId: input.targetId }, state.snapshot), (previous) => [
+                holderIdOf(previous, input.targetId),
+            ]));
+        },
     });
     const move_block = defineTool({
         id: "move_block",
@@ -283,15 +367,17 @@ export function createReportAuthoringTools(state) {
         inputSchema: moveBlockInput,
         executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `move ${input.targetId}`,
-        execute: async (input) => {
+        execute: async (input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok(refuse(opened.error));
+            }
+            const { threadId, state, token } = opened.value;
             const destination = toDestination(input);
             if (destination.isErr()) {
                 return ok(refuse(destination.error));
             }
-            return ok(land(moveBlock(draft, { targetId: input.targetId, destination: destination.value }, snapshot), (previous, next) => [
-                holderIdOf(previous, input.targetId),
-                holderIdOf(next, input.targetId),
-            ]));
+            return ok(await land(threadId, token, state.document, moveBlock(state.document, { targetId: input.targetId, destination: destination.value }, state.snapshot), (previous, next) => [holderIdOf(previous, input.targetId), holderIdOf(next, input.targetId)]));
         },
     });
     const set_title = defineTool({
@@ -302,7 +388,14 @@ export function createReportAuthoringTools(state) {
         executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `title the report ${input.title}`,
         // The title sits on the document, thus no container changes its child order.
-        execute: async (input) => ok(land(ok(setTitle(draft, input.title)), () => [])),
+        execute: async (input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok(refuse(opened.error));
+            }
+            const { threadId, state, token } = opened.value;
+            return ok(await land(threadId, token, state.document, ok(setTitle(state.document, input.title)), () => []));
+        },
     });
     const read_outline = defineTool({
         id: "read_outline",
@@ -313,7 +406,13 @@ export function createReportAuthoringTools(state) {
         executionMode: AUTHORING_EXECUTION_MODE,
         // The input carries no field, thus a hook can only restate the name of the tool.
         describeCall: "none",
-        execute: async () => ok({ outline: buildOutline(draft) }),
+        execute: async (_input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok({ refused: opened.error });
+            }
+            return ok({ outline: buildOutline(opened.value.state.document) });
+        },
     });
     const read_block = defineTool({
         id: "read_block",
@@ -322,8 +421,12 @@ export function createReportAuthoringTools(state) {
         inputSchema: readBlockInput,
         executionMode: AUTHORING_EXECUTION_MODE,
         describeCall: (input) => `read ${input.targetId}`,
-        execute: async (input) => {
-            const block = readBlock(draft, input.targetId);
+        execute: async (input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok({ refused: opened.error });
+            }
+            const block = readBlock(opened.value.state.document, input.targetId);
             const result = block !== undefined ? { found: true, block } : { found: false };
             return ok(result);
         },
@@ -336,7 +439,13 @@ export function createReportAuthoringTools(state) {
         executionMode: AUTHORING_EXECUTION_MODE,
         // The input carries no field, thus a hook can only restate the name of the tool.
         describeCall: "none",
-        execute: async () => ok(finishDraft(draft, snapshot)),
+        execute: async (_input, ctx) => {
+            const opened = await openThread(ctx);
+            if (opened.isErr()) {
+                return ok({ refused: opened.error });
+            }
+            return ok(finishDraft(opened.value.state.document, opened.value.state.snapshot));
+        },
     });
     return {
         add_block,
@@ -347,6 +456,5 @@ export function createReportAuthoringTools(state) {
         read_outline,
         read_block,
         finish_draft,
-        currentDraft: () => draft,
     };
 }

package/dist/tools/report-session/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The report-session tool barrel.
+ *
+ * These tools serve a `report` thread. The runtime constructs them over the session-state gateway and the
+ * render seams, thus each tool binds the per-session state to the thread of the call. The barrel exports
+ * the factories and their public types for the composition root.
+ */
+export { createPreviewReportTool, type PreviewReportInput, type PreviewReportResult, type PreviewReportToolDeps } from "./preview-report.js";

package/dist/tools/report-session/index.js

@@ -0,0 +1,8 @@
+/**
+ * The report-session tool barrel.
+ *
+ * These tools serve a `report` thread. The runtime constructs them over the session-state gateway and the
+ * render seams, thus each tool binds the per-session state to the thread of the call. The barrel exports
+ * the factories and their public types for the composition root.
+ */
+export { createPreviewReportTool } from "./preview-report.js";

package/dist/tools/report-session/preview-report.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The render-and-preview tool of a report session.
+ *
+ * The tool renders the current draft of a thread. It runs the finish first, because a mid-composition
+ * draft is not a `ReportDocument`. A gap list returns as data, and no render runs. On a pass the tool
+ * resolves each reference through the injected resolver, bridges the resolved values into the render model,
+ * and renders the page.
+ *
+ * The page and its staged image assets land in `report-sessions/{threadId}/` under the workspace root. That
+ * namespace belongs to this path alone, thus the tool never writes under the old `previews/` or `reports/`
+ * trees. The result carries the absolute page path, thus a local host shows the page with no seam.
+ *
+ * The result carries no access grant. `PreviewPublisher` authorizes the URL space
+ * `previews/{analysisId}/{previewId}` (`contracts/content-url.ts`), and that space cannot name a page of
+ * this tree. A hosted view of a session page is a later capability, with a URL space of its own.
+ *
+ * Each degraded condition is a typed outcome in the ok channel: a session refusal, a gap list, a resolver
+ * absence, an unresolved reference, a bridge mismatch, a render problem, a figure that escapes the
+ * workspace root, and a write failure. The tool never throws for one of them. The filesystem speaks the
+ * throw protocol, and the workspace-root seam signals an unresolvable resource the same way. Thus the
+ * write runs through the `tryFs` glue, which turns a genuine fault into the ok-channel outcome and lets a
+ * control-flow exception propagate.
+ */
+import { z } from "zod";
+import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
+import { type Logger } from "../../lib/logger.js";
+import { type FinishGap } from "../../report-model/draft-finish.js";
+import type { ReferenceResolver } from "../../report-model/reference-resolver.js";
+import { type ResolutionFailure } from "../../report-model/validate.js";
+import { type BridgeMismatch } from "../../report-render/value-bridge.js";
+import type { RenderProblem } from "../../report-render/types.js";
+import { type Tool } from "../define-tool.js";
+import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
+/** The empty input. The tool renders the current draft of the thread, thus it needs no field. */
+declare const previewReportInput: z.ZodObject<{}, z.core.$strip>;
+export type PreviewReportInput = z.infer<typeof previewReportInput>;
+/**
+ * The typed outcome of the preview tool. Each arm is ok-channel data, thus the tool never throws for a
+ * degraded condition. `rendered` carries the absolute page path.
+ */
+export type PreviewReportResult = {
+    outcome: "refused";
+    refusal: SessionRefusal;
+} | {
+    outcome: "gaps";
+    gaps: FinishGap[];
+} | {
+    outcome: "resolver-unavailable";
+} | {
+    outcome: "unresolved-references";
+    unresolved: ResolutionFailure[];
+} | {
+    outcome: "bridge-mismatch";
+    mismatches: BridgeMismatch[];
+} | {
+    outcome: "render-problems";
+    problems: RenderProblem[];
+} | {
+    outcome: "figure-out-of-scope";
+    blockId: string;
+    path: string;
+} | {
+    outcome: "write-failed";
+    detail: string;
+} | {
+    outcome: "rendered";
+    pagePath: string;
+};
+/**
+ * The construction deps of the preview tool.
+ *
+ * `resolveWorkspaceRoot` maps the analysis of the call onto its workspace root, thus one singleton tool
+ * serves every analysis and it resolves the root per call from the scope. `resolver` is optional, because a
+ * resolver realization can be absent.
+ */
+export interface PreviewReportToolDeps {
+    readonly gateway: ReportSessionStateGateway;
+    readonly resolver?: ReferenceResolver;
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    readonly logger?: Logger;
+}
+/**
+ * Make the render-and-preview tool over the session-state gateway and the render seams.
+ *
+ * The tool reads the thread id from the scope of the call, and it loads the state through the gateway. Thus
+ * one factory serves every thread. The tool holds no per-session value, and it resolves the root of the
+ * analysis of the call.
+ */
+export declare function createPreviewReportTool(deps: PreviewReportToolDeps): Tool<PreviewReportInput, PreviewReportResult>;
+export {};