@inflexa-ai/harness 0.18.0 → 0.19.1

package/dist/tools/define-tool.js

@@ -20,6 +20,32 @@ import { z } from "zod";
 export function isToolError(value) {
     return typeof value === "object" && value !== null && typeof value.error === "string" && typeof value.retryable === "boolean";
 }
+/**
+ * The reserved key that carries a picture on a tool ok value. It is a symbol,
+ * thus it never collides with a data field. `JSON.stringify` also omits a symbol
+ * key, thus the bytes never reach the JSON text by accident.
+ */
+export const toolResultImageKey = Symbol("toolResultImage");
+/**
+ * Attach a picture to a tool ok value. The value keeps its own fields, and the
+ * picture rides under the reserved key. The loop reads the key, and it moves the
+ * bytes into an image content block on the tool result.
+ */
+export function withToolResultImage(value, image) {
+    return { ...value, [toolResultImageKey]: image };
+}
+/** Read the picture that a tool ok value carries, or undefined when it carries none. */
+export function readToolResultImage(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const image = value[toolResultImageKey];
+    if (typeof image !== "object" || image === null)
+        return undefined;
+    const { base64, mediaType } = image;
+    if (typeof base64 !== "string" || typeof mediaType !== "string")
+        return undefined;
+    return { base64, mediaType };
+}
 /**
  * Package a `Tool`. The emitted JSON Schema must have a top-level
  * `"type": "object"` — model tool calling rejects anything else. A `z.discriminatedUnion`

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

@@ -17,7 +17,7 @@
  * has to be able to see without reading the model transcript.
  */
 import { type Tool } from "../define-tool.js";
-import { type ChromeConfig } from "../../lib/chrome.js";
+import type { ChromeConfig } from "../../lib/chrome.js";
 import type { Logger } from "../../lib/logger.js";
 import { type PreviewPublisher } from "./preview-publisher.js";
 import type { PreviewUrlCell } from "./mint-preview-url.js";

package/dist/tools/report/preview-snapshot.js

@@ -19,11 +19,9 @@
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
-import { withPage } from "../../lib/chrome.js";
+import { capturePage } from "../../lib/page-capture.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
 import { describeMintFailure } from "./preview-publisher.js";
-const NAV_TIMEOUT_MS = 20_000;
-const READY_TIMEOUT_MS = 8_000;
 const WAIT_MS_CAP = 30_000;
 export function createPreviewSnapshotTool(state) {
     const logger = (state.logger ?? createNoopLogger()).named("preview-snapshot").with({ previewId: state.previewId });
@@ -75,53 +73,16 @@ export function createPreviewSnapshotTool(state) {
                 state.urlCell.expiresAt = result.data.expiresAt;
             }
             try {
-                return ok(await withPage(state.chrome, async (page) => {
-                    const consoleErrors = [];
-                    const failedRequests = [];
-                    page.on("console", (msg) => {
-                        if (msg.type() === "error")
-                            consoleErrors.push(msg.text());
-                    });
-                    page.on("pageerror", (err) => consoleErrors.push(`pageerror: ${err.message}`));
-                    page.on("requestfailed", (req) => {
-                        failedRequests.push({
-                            url: req.url(),
-                            reason: req.failure()?.errorText ?? "unknown",
-                        });
-                    });
-                    await page.goto(url, {
-                        waitUntil: "networkidle2",
-                        timeout: NAV_TIMEOUT_MS,
-                    });
-                    // Wait for the inflexa-theme-ready event (fired after echarts theme
-                    // registers). Check the `__inflexaThemeReady` sentinel first because
-                    // the page already deferred its dispatch — by the time we get here
-                    // via networkidle2, the event has likely already fired and a plain
-                    // addEventListener would block forever. The callback runs in the
-                    // browser context.
-                    await page
-                        .evaluate(new Function("timeout", "return new Promise(function(resolve){if(window.__inflexaThemeReady){resolve();return;}var t=setTimeout(resolve,timeout);document.addEventListener('inflexa-theme-ready',function(){clearTimeout(t);resolve();},{once:true});});"), READY_TIMEOUT_MS)
-                        .catch(() => {
-                        /* fall through — capture state as-is */
-                    });
-                    if (input.waitForSelector) {
-                        await page.waitForSelector(input.waitForSelector, { timeout: 5_000 }).catch(() => {
-                            /* not fatal */
-                        });
-                    }
-                    if (input.waitMs)
-                        await new Promise((r) => setTimeout(r, input.waitMs));
-                    const screenshot = await page.screenshot({
-                        encoding: "base64",
-                        fullPage: false,
-                    });
-                    return {
-                        ok: true,
-                        screenshotBase64: typeof screenshot === "string" ? screenshot : Buffer.from(screenshot).toString("base64"),
-                        consoleErrors,
-                        failedRequests,
-                    };
-                }));
+                const captured = await capturePage(state.chrome, url, {
+                    ...(input.waitForSelector !== undefined ? { waitForSelector: input.waitForSelector } : {}),
+                    ...(input.waitMs !== undefined ? { waitMs: input.waitMs } : {}),
+                });
+                return ok({
+                    ok: true,
+                    screenshotBase64: captured.screenshotBase64,
+                    consoleErrors: captured.consoleErrors,
+                    failedRequests: captured.failedRequests,
+                });
             }
             catch (err) {
                 return ok({

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,155 @@ 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 result of `finish_draft`. A load that gives no state refuses instead of a finish outcome. */
+export type FinishToolResult = FinishResult | {
+    refused: SessionRefusal;
 };
-/** The state that the factory closes over. */
-export interface ReportAuthoringState {
+/** 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, the
+ * concurrency token, and the seen-document hash of the look-before-record rule. `absent` and `wrong-type`
+ * are permanent conditions, and `failed` is a transient fault that names its cause.
+ *
+ * `seenDocumentHash` is the hash that the last eyes capture saw, or `null` before the first look. The record
+ * tool compares it against the hash of the current draft, thus a never-seen page and a stale look each
+ * refuse.
+ */
+export type SessionStateLoad = {
+    outcome: "found";
+    state: ReportSessionState;
+    analysisId: string;
+    token: SessionStateToken;
+    seenDocumentHash: string | null;
+} | {
+    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 outcome of a gateway stamp. `stamped` wrote the marker. `absent` means that no row holds the thread.
+ * `failed` is a transient store fault that names its cause. Each arm is plain data, thus a stamp never
+ * throws for one of them.
+ */
+export type StampResult = {
+    outcome: "stamped";
+} | {
+    outcome: "absent";
+} | {
+    outcome: "failed";
+    detail: string;
+};
+/**
+ * The outcome of the seen stamp through the gateway. `stamped` copied a rendered hash onto the seen hash.
+ * `no-rendered` means that the row holds no rendered hash to copy, thus no preview stamped one. `absent`
+ * means that no row holds the thread. `failed` is a transient store fault that names its cause. Each arm is
+ * plain data, thus a stamp never throws for one of them.
+ */
+export type SeenStampResult = {
+    outcome: "stamped";
+} | {
+    outcome: "no-rendered";
+} | {
+    outcome: "absent";
+} | {
+    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>;
+    /**
+     * Stamp the hash of the rendered draft on the session state. The preview calls it when the page lands,
+     * thus the runtime knows which draft the page shows.
+     */
+    stampRendered(threadId: string, hash: string): Promise<StampResult>;
+    /**
+     * Copy the rendered hash onto the seen hash. The eyes call it after a capture, thus the seen hash holds
+     * the hash of the draft that the picture shows, and never the current one. The outcome names whether a
+     * rendered hash existed to copy, thus the eyes tell a real stamp from a missed one.
+     */
+    stampSeen(threadId: string): Promise<SeenStampResult>;
+}
+/**
+ * The thread of a call, its analysis, the loaded state, the concurrency token that the persist compares
+ * against, and the seen-document hash of the look-before-record rule.
+ */
+export interface OpenedThread {
+    readonly threadId: string;
+    readonly analysisId: string;
+    readonly state: ReportSessionState;
+    readonly token: SessionStateToken;
+    /** The hash that the last eyes capture saw, or `null` before the first look. */
+    readonly seenDocumentHash: string | null;
+}
+/**
+ * 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 +278,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 {};