@inflexa-ai/harness 0.38.0 → 0.39.0

package/dist/billing/cached-resolver.d.ts

@@ -3,21 +3,25 @@
  *
  * Resolves an input to a value via `fetch`, caching success only behind a
  * bounded LRU with per-entry TTL. Concurrent callers for the same key coalesce
- * onto one in-flight fetch; a fetch that throws is not cached and clears its
- * in-flight slot. Callers supply their own key formula, fetch+validate step,
- * and (optionally) cache hit/miss metrics; this module owns eviction,
- * coalescing, and expiry — the deep, drift-prone plumbing.
+ * onto one in-flight fetch and share its outcome. An `err` is never cached:
+ * a host that gates spend per caller must see every refusal again, and a
+ * cached refusal or a cached transient fault would outlive its cause. A fetch
+ * that rejects is a defect: it is not cached, it clears its in-flight slot,
+ * and the rejection passes through. Callers supply their own key formula,
+ * fetch+validate step, and (optionally) cache hit/miss metrics; this module
+ * owns eviction, coalescing, and expiry — the deep, drift-prone plumbing.
  */
+import { ResultAsync } from "neverthrow";
 export interface CachedResolverMetrics {
     onHit(): void;
     /** Recorded once per upstream fetch — coalesced callers do not count. */
     onMiss(): void;
 }
-export interface CachedResolverConfig<In, Out> {
+export interface CachedResolverConfig<In, Out, E> {
     readonly ttlMs: number;
     readonly maxEntries: number;
     readonly keyFn: (input: In) => string;
-    readonly fetch: (input: In) => Promise<Out>;
+    readonly fetch: (input: In) => ResultAsync<Out, E>;
     readonly metrics?: CachedResolverMetrics;
 }
-export declare function createCachedResolver<In, Out>(cfg: CachedResolverConfig<In, Out>): (input: In) => Promise<Out>;
+export declare function createCachedResolver<In, Out, E>(cfg: CachedResolverConfig<In, Out, E>): (input: In) => ResultAsync<Out, E>;

package/dist/billing/cached-resolver.js

@@ -3,11 +3,15 @@
  *
  * Resolves an input to a value via `fetch`, caching success only behind a
  * bounded LRU with per-entry TTL. Concurrent callers for the same key coalesce
- * onto one in-flight fetch; a fetch that throws is not cached and clears its
- * in-flight slot. Callers supply their own key formula, fetch+validate step,
- * and (optionally) cache hit/miss metrics; this module owns eviction,
- * coalescing, and expiry — the deep, drift-prone plumbing.
+ * onto one in-flight fetch and share its outcome. An `err` is never cached:
+ * a host that gates spend per caller must see every refusal again, and a
+ * cached refusal or a cached transient fault would outlive its cause. A fetch
+ * that rejects is a defect: it is not cached, it clears its in-flight slot,
+ * and the rejection passes through. Callers supply their own key formula,
+ * fetch+validate step, and (optionally) cache hit/miss metrics; this module
+ * owns eviction, coalescing, and expiry — the deep, drift-prone plumbing.
  */
+import { ResultAsync, ok } from "neverthrow";
 export function createCachedResolver(cfg) {
     // Map insertion order doubles as LRU recency: a hit re-inserts the key at
     // the tail; eviction drops the head (oldest).
@@ -23,7 +27,7 @@ export function createCachedResolver(cfg) {
         }
         cache.delete(key);
         cache.set(key, entry);
-        return entry.value;
+        return entry;
     }
     function store(key, value) {
         cache.set(key, { value, expiresAt: Date.now() + cfg.ttlMs });
@@ -34,21 +38,22 @@ export function createCachedResolver(cfg) {
             cache.delete(oldest);
         }
     }
-    return async function resolve(input) {
+    async function resolve(input) {
         const key = cfg.keyFn(input);
         const fresh = readFresh(key);
         if (fresh !== undefined) {
             cfg.metrics?.onHit();
-            return fresh;
+            return ok(fresh.value);
         }
         const pending = inflight.get(key);
         if (pending)
             return pending;
         cfg.metrics?.onMiss();
         const promise = (async () => {
-            const value = await cfg.fetch(input);
-            store(key, value);
-            return value;
+            const fetched = await cfg.fetch(input);
+            if (fetched.isOk())
+                store(key, fetched.value);
+            return fetched;
         })();
         inflight.set(key, promise);
         try {
@@ -57,5 +62,6 @@ export function createCachedResolver(cfg) {
         finally {
             inflight.delete(key);
         }
-    };
+    }
+    return (input) => new ResultAsync(resolve(input));
 }

package/dist/index.d.ts

@@ -35,7 +35,7 @@ export type { ArtifactRegistry, ArtifactRegistrationInput, ArtifactSyncInput, Ex
 export type { ArtifactManifestEntry } from "./schemas/artifact-manifest.js";
 export type { ProvenanceCollector } from "./provenance/collector.js";
 export { UnavailableSessionPagePublisher } from "./tools/report-session/session-page-publisher.js";
-export type { MakeSessionPagePublisher, SessionPagePublisher, SessionPageMintResult } from "./tools/report-session/session-page-publisher.js";
+export type { MakeSessionPagePublisher, SessionPageGrant, SessionPageMintFailure, SessionPagePublisher, } from "./tools/report-session/session-page-publisher.js";
 export type { ResolvePageUrl, SessionPageAccess } from "./tools/report-session/index.js";
 export { bindReadExport, bindSessionEmit } from "./provenance/seam.js";
 export type { ProvenanceExport, ProvenanceSeam, RunProvenanceEvent, SessionProvenanceEvent } from "./provenance/seam.js";

package/dist/sandbox/types.d.ts

@@ -144,8 +144,12 @@ export type PackageRequestOutcome = {
  *
  * The seam speaks the query of the `package-identity` capability, thus the
  * host resolves the identity and the harness never folds a name.
+ *
+ * A failure of one package is an outcome. An `err` means that the whole
+ * call gave no answer, and the harness reads it as `unavailable` for each
+ * query.
  */
-export type ExtendAnalysisFarm = (analysisId: string, queries: readonly PackageQuery[]) => Promise<readonly PackageRequestOutcome[]>;
+export type ExtendAnalysisFarm = (analysisId: string, queries: readonly PackageQuery[]) => ResultAsync<readonly PackageRequestOutcome[], GateFailure>;
 /**
  * Per-sandbox-machine liveness verdict. `oomKilled` is meaningful only when
  * `alive` is false: true when the backend reports the machine was killed for

package/dist/tools/execute-analysis.js

@@ -19,6 +19,7 @@ import { routeAdHocRequest } from "./ad-hoc-router.js";
 import { adHocPlanId, adHocRunId } from "./analysis-invocation.js";
 import { defineTool } from "./define-tool.js";
 import { queryPackages, readInventorySections } from "./sandbox/list-available-packages.js";
+import { callExtendAnalysisFarm } from "./sandbox/link-packages.js";
 const planIdSchema = z.string().regex(/^pln-[a-f0-9]{8}$/, "planId must be a pln-<8hex> value");
 const inputSchema = z
     .object({
@@ -120,16 +121,13 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
     const queries = [...union.values()];
     if (queries.length === 0)
         return 0;
-    let outcomes;
-    try {
-        outcomes = await extendAnalysisFarm(analysisId, queries);
-    }
-    catch (cause) {
-        // A realization throw is an `unavailable` answer, not a driver error.
-        // The sibling resolver seam maps a throw the same way (farm.ts), and
-        // the planner can act on "the store cannot answer" — not on a stack.
-        throw new PlanPackagesMissingError([], [], cause instanceof Error ? cause.message : String(cause));
+    const linked = await callExtendAnalysisFarm(extendAnalysisFarm, analysisId, queries);
+    if (linked.isErr()) {
+        // A call that gave no answer is an `unavailable` answer, not a driver
+        // error: the planner can act on "the store cannot answer".
+        throw new PlanPackagesMissingError([], [], linked.error);
     }
+    const outcomes = linked.value;
     // An `unavailable` outcome preempts everything: the link pass could not
     // answer at all (an unreadable graph, a locked farm), so a per-package
     // absence list would be a fabrication. One reason covers the batch.

package/dist/tools/report-session/examine-page.d.ts

@@ -37,16 +37,19 @@
  * one and the look cannot count. The tool then gives a missed-stamp outcome that directs a new preview,
  * because a repeated look never stamps a marker that no preview wrote.
  *
- * The eyes seam, the chrome navigation, and the workspace-root seam each speak the throw protocol. The tool
- * guards each of them, thus a fault of a look becomes a typed outcome and the loop never sees a throw.
+ * The eyes seam, the chrome navigation, and the workspace-root seam each speak the throw protocol. The URL
+ * seam gives a `Result`. The tool guards each of them, thus a fault of a look becomes a typed outcome and
+ * the loop never sees a throw.
  *
  * A hang is not a throw, and a guard alone never ends one. Thus the acquire and the release each carry a
  * deadline. A realization that hangs while it starts a browser would otherwise hold the whole agent turn,
  * and no outcome would ever arrive.
  */
+import { type ResultAsync } from "neverthrow";
 import { z } from "zod";
 import type { AuthContext } from "../../auth/types.js";
 import { type ChromeConfig } from "../../lib/chrome.js";
+import type { GateFailure } from "../../lib/hooks.js";
 import { type AcquireEyes } from "../../lib/eyes.js";
 import { type Logger } from "../../lib/logger.js";
 import { type CaptureCoverage, type CapturePage, type FailedRequest, type PageCapture } from "../../lib/page-capture.js";
@@ -65,7 +68,7 @@ export type ResolvePageUrl = (args: {
     analysisId: string;
     threadId: string;
     auth: AuthContext;
-}) => Promise<string>;
+}) => ResultAsync<string, GateFailure>;
 /** The empty input. The tool examines the current page of the thread, thus it needs no field. */
 declare const examinePageInput: z.ZodObject<{}, z.core.$strip>;
 export type ExaminePageInput = z.infer<typeof examinePageInput>;

package/dist/tools/report-session/examine-page.js

@@ -37,8 +37,9 @@
  * one and the look cannot count. The tool then gives a missed-stamp outcome that directs a new preview,
  * because a repeated look never stamps a marker that no preview wrote.
  *
- * The eyes seam, the chrome navigation, and the workspace-root seam each speak the throw protocol. The tool
- * guards each of them, thus a fault of a look becomes a typed outcome and the loop never sees a throw.
+ * The eyes seam, the chrome navigation, and the workspace-root seam each speak the throw protocol. The URL
+ * seam gives a `Result`. The tool guards each of them, thus a fault of a look becomes a typed outcome and
+ * the loop never sees a throw.
  *
  * A hang is not a throw, and a guard alone never ends one. Thus the acquire and the release each carry a
  * deadline. A realization that hangs while it starts a browser would otherwise hold the whole agent turn,
@@ -273,14 +274,21 @@ export function createExaminePageTool(deps) {
                 logger.warn("the session page could not be read", { threadId, analysisId, ...defaultErrorFields(cause) });
                 return ok({ outcome: "capture-failed", detail: "the session page could not be read" });
             }
-            // The URL seam speaks the throw protocol like the other seams, thus a fault of the formation
-            // becomes a typed outcome and the look never starts.
+            // An `err` of the URL seam and a rejected realization each become a typed outcome, and the look
+            // never starts.
             let url;
             try {
-                url =
-                    deps.resolvePageUrl !== undefined
-                        ? await deps.resolvePageUrl({ pagePath, analysisId, threadId, auth: ctx.session.auth })
-                        : pathToFileURL(pagePath).href;
+                if (deps.resolvePageUrl === undefined) {
+                    url = pathToFileURL(pagePath).href;
+                }
+                else {
+                    const resolved = await deps.resolvePageUrl({ pagePath, analysisId, threadId, auth: ctx.session.auth });
+                    if (resolved.isErr()) {
+                        logger.warn("the page URL did not resolve", { threadId, analysisId, reason: resolved.error.reason });
+                        return ok({ outcome: "capture-failed", detail: "the page URL did not resolve" });
+                    }
+                    url = resolved.value;
+                }
             }
             catch (cause) {
                 logger.warn("the page URL did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });

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

@@ -7,7 +7,7 @@
  */
 export { createPreviewReportTool, type PreviewReportInput, type PreviewReportResult, type PreviewReportToolDeps, type ResolvePageAsset, type SessionPageAccess, } from "./preview-report.js";
 export { createExaminePageTool, type CaptureCoverage, type CapturePage, type ExaminedTile, type ExaminePageInput, type ExaminePageResult, type ExaminePageToolDeps, type FailedRequest, type PageCapture, type ResolvePageUrl, } from "./examine-page.js";
-export { describeSessionPageMintFailure, UnavailableSessionPagePublisher, type MakeSessionPagePublisher, type SessionPageMintFailure, type SessionPageMintResult, type SessionPagePublisher, } from "./session-page-publisher.js";
+export { describeSessionPageMintFailure, UnavailableSessionPagePublisher, type MakeSessionPagePublisher, type SessionPageGrant, type SessionPageMintFailure, type SessionPagePublisher, } from "./session-page-publisher.js";
 export { createRecordVersionTool, type RecordVersionInput, type RecordVersionResult, type RecordVersionToolDeps } from "./record-version.js";
 export { createDeriveTableTool, type DeriveTableInput, type DeriveTableResult, type DeriveTableToolDeps } from "./derive-table.js";
 export { createListPinnedArtifactsTool, type ListPinnedArtifactsInput, type ListPinnedArtifactsResult, type ListPinnedArtifactsToolDeps, type PinnedArtifact, type PinnedCitation, } from "./list-artifacts.js";

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

@@ -350,7 +350,7 @@ async function sweepAssets(assetsDir, staged, logger) {
  *
  * An absent factory gives no grant, and the arm carries no access field — the page path stays the whole
  * local contract. The tool builds the publisher over the scope of the call, thus the mint runs under the
- * auth of the caller. A refusal, a thrown construction, and a thrown realization each become the
+ * auth of the caller. An `err`, a thrown construction, and a rejected realization each become the
  * not-granted arm, thus a broken grant surface never costs the render. The URL spells through
  * `buildReportSessionUrl`, thus the formula lives in the contract and the seam gives the content-server
  * base alone.
@@ -359,22 +359,24 @@ async function mintAccess(makeSessionPages, analysisId, threadId, auth, logger)
     if (makeSessionPages === undefined) {
         return undefined;
     }
-    let minted;
+    let grant;
     try {
-        minted = await makeSessionPages({ analysisId, auth }).mintSessionPageAccess(threadId);
+        const minted = await makeSessionPages({ analysisId, auth }).mintSessionPageAccess(threadId);
+        if (minted.isErr()) {
+            const detail = describeSessionPageMintFailure(minted.error);
+            logger.warn("the session-page mint refused", { threadId, analysisId, detail });
+            return { granted: false, detail };
+        }
+        grant = minted.value;
     }
     catch (cause) {
         logger.warn("the session-page mint threw", { threadId, analysisId, ...defaultErrorFields(cause) });
         return { granted: false, detail: "session-page-access mint failed" };
     }
-    if (!minted.ok) {
-        logger.warn("the session-page mint refused", { threadId, analysisId, detail: describeSessionPageMintFailure(minted) });
-        return { granted: false, detail: describeSessionPageMintFailure(minted) };
-    }
     return {
         granted: true,
-        url: buildReportSessionUrl(minted.data.baseUrl, analysisId, threadId, "index.html", minted.data.token),
-        expiresAt: minted.data.expiresAt,
+        url: buildReportSessionUrl(grant.baseUrl, analysisId, threadId, "index.html", grant.token),
+        expiresAt: grant.expiresAt,
     };
 }
 /**

package/dist/tools/report-session/session-page-publisher.d.ts

@@ -11,28 +11,24 @@
  * tool call, thus the composition binds a factory and the preview tool builds the publisher over the
  * scope of the call — exactly as it builds the reference resolver. A boot-time singleton could not
  * carry that credential, and a host that bans ambient state could not bind one at all. The local
- * default (`UnavailableSessionPagePublisher`) returns not-ok, thus the preview tool attaches no URL
+ * default (`UnavailableSessionPagePublisher`) gives an `err`, thus the preview tool attaches no URL
  * and the render still lands — the page path stays the whole local contract.
  */
+import { type ResultAsync } from "neverthrow";
 import type { AuthContext } from "../../auth/types.js";
-export type SessionPageMintResult = {
-    ok: true;
-    data: {
-        baseUrl: string;
-        token: string;
-        expiresAt: string;
-    };
-} | {
-    ok: false;
-    status?: number;
-    error: {
-        message?: string;
+/** The grant of one session page: the content-server base, the token, and its expiry. */
+export interface SessionPageGrant {
+    readonly baseUrl: string;
+    readonly token: string;
+    readonly expiresAt: string;
+}
+/** What a failed mint is allowed to carry. */
+export interface SessionPageMintFailure {
+    readonly status?: number;
+    readonly error: {
+        readonly message?: string;
     };
-};
-/** The not-ok arm of the seam's result — what a failed mint is allowed to carry. */
-export type SessionPageMintFailure = Extract<SessionPageMintResult, {
-    ok: false;
-}>;
+}
 /**
  * Renders a failed mint as the line an agent reads back from the preview tool.
  *
@@ -49,7 +45,7 @@ export interface SessionPagePublisher {
      * caller spells the whole URL through `buildReportSessionUrl`, thus the formula lives in the
      * contract and never in a realization.
      */
-    mintSessionPageAccess(threadId: string): Promise<SessionPageMintResult>;
+    mintSessionPageAccess(threadId: string): ResultAsync<SessionPageGrant, SessionPageMintFailure>;
 }
 /**
  * The per-call construction of the publisher. The factory binds one analysis and the auth of the tool
@@ -60,9 +56,9 @@ export type MakeSessionPagePublisher = (scope: {
     auth: AuthContext;
 }) => SessionPagePublisher;
 /**
- * Local default — no hosted view of a session page. Returns not-ok, thus the preview tool carries the
+ * Local default — no hosted view of a session page. Gives an `err`, thus the preview tool carries the
  * refusal as data and the page path stays the whole result.
  */
 export declare class UnavailableSessionPagePublisher implements SessionPagePublisher {
-    mintSessionPageAccess(_threadId: string): Promise<SessionPageMintResult>;
+    mintSessionPageAccess(_threadId: string): ResultAsync<SessionPageGrant, SessionPageMintFailure>;
 }

package/dist/tools/report-session/session-page-publisher.js

@@ -11,9 +11,10 @@
  * tool call, thus the composition binds a factory and the preview tool builds the publisher over the
  * scope of the call — exactly as it builds the reference resolver. A boot-time singleton could not
  * carry that credential, and a host that bans ambient state could not bind one at all. The local
- * default (`UnavailableSessionPagePublisher`) returns not-ok, thus the preview tool attaches no URL
+ * default (`UnavailableSessionPagePublisher`) gives an `err`, thus the preview tool attaches no URL
  * and the render still lands — the page path stays the whole local contract.
  */
+import { errAsync } from "neverthrow";
 /**
  * Renders a failed mint as the line an agent reads back from the preview tool.
  *
@@ -32,14 +33,11 @@ export function describeSessionPageMintFailure(failure) {
     return detail.length > 0 ? `session-page-access mint failed: ${detail.join(" ")}` : "session-page-access mint failed";
 }
 /**
- * Local default — no hosted view of a session page. Returns not-ok, thus the preview tool carries the
+ * Local default — no hosted view of a session page. Gives an `err`, thus the preview tool carries the
  * refusal as data and the page path stays the whole result.
  */
 export class UnavailableSessionPagePublisher {
-    async mintSessionPageAccess(_threadId) {
-        return {
-            ok: false,
-            error: { message: "the hosted view of a session page is unavailable in this environment" },
-        };
+    mintSessionPageAccess(_threadId) {
+        return errAsync({ error: { message: "the hosted view of a session page is unavailable in this environment" } });
     }
 }

package/dist/tools/sandbox/link-packages.d.ts

@@ -13,6 +13,8 @@
  * capability, thus the agent learns one grammar for the plan, the tool, and
  * the prompt layer.
  */
+import { type Result } from "neverthrow";
+import { type PackageQuery } from "../../sandbox/package-identity.js";
 import type { ExtendAnalysisFarm, PackageRequestOutcome } from "../../sandbox/types.js";
 export interface LinkPackagesDeps {
     readonly extendAnalysisFarm: ExtendAnalysisFarm;
@@ -22,6 +24,12 @@ export interface LinkPackagesDeps {
 export interface LinkPackagesResult {
     readonly outcomes: readonly PackageRequestOutcome[];
 }
+/**
+ * Call the seam, and give the outcomes or the one reason that the call gave
+ * no answer. An `err` and a rejected realization each give that reason, thus
+ * no call site sees a throw.
+ */
+export declare function callExtendAnalysisFarm(extendAnalysisFarm: ExtendAnalysisFarm, analysisId: string, queries: readonly PackageQuery[]): Promise<Result<readonly PackageRequestOutcome[], string>>;
 export declare function createLinkPackagesTool(deps: LinkPackagesDeps): import("../define-tool.js").Tool<{
     packages: string[];
 }, LinkPackagesResult>;

package/dist/tools/sandbox/link-packages.js

@@ -34,6 +34,19 @@ function describeParseError(entry, error) {
             return `"${entry}" pins with the specifier "${error.specifier}", which this tool cannot honor — pass a bare name, or name==version with one exact version`;
     }
 }
+/**
+ * Call the seam, and give the outcomes or the one reason that the call gave
+ * no answer. An `err` and a rejected realization each give that reason, thus
+ * no call site sees a throw.
+ */
+export async function callExtendAnalysisFarm(extendAnalysisFarm, analysisId, queries) {
+    try {
+        return (await extendAnalysisFarm(analysisId, queries)).mapErr((failure) => failure.reason);
+    }
+    catch (cause) {
+        return err(cause instanceof Error ? cause.message : String(cause));
+    }
+}
 export function createLinkPackagesTool(deps) {
     return defineTool({
         id: "link_packages",
@@ -67,17 +80,14 @@ export function createLinkPackagesTool(deps) {
                 }
                 queries.push(parsed.value);
             }
-            // A realization throw reads as `unavailable` per query. The loop
-            // would render the throw as a raw tool error, and a raw driver
-            // message teaches the agent nothing that `reason` does not.
-            try {
-                const outcomes = await deps.extendAnalysisFarm(deps.analysisId, queries);
-                return ok({ outcomes });
-            }
-            catch (cause) {
-                const reason = cause instanceof Error ? cause.message : String(cause);
+            // A call that gave no answer reads as `unavailable` per query. A
+            // raw tool error teaches the agent nothing that `reason` does not.
+            const linked = await callExtendAnalysisFarm(deps.extendAnalysisFarm, deps.analysisId, queries);
+            if (linked.isErr()) {
+                const reason = linked.error;
                 return ok({ outcomes: queries.map((query) => ({ kind: "unavailable", spelling: query.spelling, reason })) });
             }
+            return ok({ outcomes: linked.value });
         },
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.38.0",
+    "version": "0.39.0",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",