@inflexa-ai/harness 0.21.1 → 0.22.0

package/dist/agents/report-session-agent.d.ts

@@ -38,7 +38,7 @@ import type { ThreadStore } from "../memory/thread-store.js";
 import type { ReferenceResolver } from "../report-model/reference-resolver.js";
 import type { ReportVersionStore } from "../state/report-versions.js";
 import type { ReportSessionStateGateway } from "../tools/report-authoring/authoring-tools.js";
-import { type ResolvePageAsset } from "../tools/report-session/index.js";
+import { type ResolvePageAsset, type ResolvePageUrl, type SessionPagePublisher } from "../tools/report-session/index.js";
 /** Canonical agent id -- distinct from the id of the old templating agent. */
 export declare const REPORT_SESSION_AGENT_ID: "report-session";
 /**
@@ -98,6 +98,18 @@ export interface ReportSessionAgentDeps {
      * installation of the harness.
      */
     readonly resolvePageAsset?: ResolvePageAsset;
+    /**
+     * Session-page publisher -- the hosted view of the rendered page. Bound, the preview
+     * tool mints one grant after the page lands and attaches the URL beside the path.
+     * Omitted, the result carries the page path alone.
+     */
+    readonly sessionPages?: SessionPagePublisher;
+    /**
+     * Page-URL formation of the eyes -- the URL that one look opens. A composition whose
+     * browser cannot reach the workspace tree binds a resolver that names a served URL.
+     * Omitted, the eyes tool navigates through a `file://` URL of the page path.
+     */
+    readonly resolvePageUrl?: ResolvePageUrl;
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
 }

package/dist/agents/report-session-agent.js

@@ -39,7 +39,7 @@ const REPORT_SESSION_MAX_ITERATIONS = 75;
 /** Build the report `AgentDefinition` with every tool bound to its deps. */
 export function createReportSessionAgent(deps) {
     const { model, pool, embedding, workspaceFs, gateway, resolveWorkspaceRoot, store, threads, chrome, eyes, makeResolver, resolvePageAsset, logger } = deps;
-    const { derivations, sandboxClient, runAuthorizer } = deps;
+    const { derivations, sandboxClient, runAuthorizer, sessionPages, resolvePageUrl } = deps;
     const authoring = createReportAuthoringTools(gateway);
     const tools = [
         // The read surface toward the analysis. It roams the tree read-only.
@@ -83,6 +83,7 @@ export function createReportSessionAgent(deps) {
             resolveWorkspaceRoot,
             ...(makeResolver ? { makeResolver } : {}),
             ...(resolvePageAsset ? { resolvePageAsset } : {}),
+            ...(sessionPages ? { sessionPages } : {}),
             ...(logger ? { logger } : {}),
         }),
         // The eyes tool. It opens the rendered page in headless Chrome.
@@ -91,6 +92,7 @@ export function createReportSessionAgent(deps) {
             resolveWorkspaceRoot,
             chrome,
             ...(eyes ? { eyes } : {}),
+            ...(resolvePageUrl ? { resolvePageUrl } : {}),
             ...(logger ? { logger } : {}),
         }),
         // The record tool. It gates the whole document, records one version, then prunes each

package/dist/contracts/content-url.d.ts

@@ -1,21 +1,29 @@
 /**
  * Content URL construction — shared between the frontend and Cortex.
  *
- * The `res` claim formula and URL shape are the canonical TypeScript contract
- * for the content-token preview flow. The storage backend mirrors the formula in Go; both
- * sides are locked by the shared test vector at
- * `src/__tests__/fixtures/preview-res.json`.
+ * The `res` claim formulas and URL shapes are the canonical TypeScript contract
+ * for the content-token flow. The storage backend mirrors each formula in Go; both
+ * sides are locked by the shared test vectors at
+ * `src/__tests__/fixtures/preview-res.json` (previews) and
+ * `src/__tests__/fixtures/report-session-res.json` (report-session pages), each a
+ * byte-identical copy of the storage backend's `kernel/contenttoken/testdata` file.
  *
- * End-to-end contract:
+ * End-to-end contract (previews):
  *   token res claim : "previews/{analysisId}/{previewId}"
  *   URL             : {contentBaseUrl}/previews/{analysisId}/{previewId}/{previewPath}?t={token}
  *   Caddy predicate : request.path.startsWith("/" + res + "/")
  *
+ * End-to-end contract (report-session pages):
+ *   token res claim : "report-sessions/{analysisId}/{threadId}"  (token kind "rs")
+ *   URL             : {contentBaseUrl}/report-sessions/{analysisId}/{threadId}/{pagePath}?t={token}
+ *   Caddy predicate : request.path.startsWith("/" + res + "/")
+ *
  * This is URL space only. On disk a preview lives inside its analysis's workspace tree, at
  * `{resolveWorkspaceRoot(analysisId)}/previews/{previewId}/{previewPath}` (the workspace-layout
- * spec) — the `res` claim carries the analysis id because the URL needs an authorization
- * boundary, whereas the resolved root already identifies the analysis and so does not repeat it.
- * A host that serves previews owns the map between the two.
+ * spec), and a session page at `{resolveWorkspaceRoot(analysisId)}/report-sessions/{threadId}/{pagePath}`
+ * (the report-session-agent spec) — the `res` claim carries the analysis id because the URL needs an
+ * authorization boundary, whereas the resolved root already identifies the analysis and so does not
+ * repeat it. A host that serves either space owns the map between the two.
  *
  * The harness's contracts module owns this TS implementation so both the harness and
  * react-client consume one canonical formula.
@@ -47,3 +55,30 @@ export declare function previewResourceId(analysisId: string, previewId: string)
  * @param token - Short-lived content token minted by the storage backend (required)
  */
 export declare function buildPreviewUrl(contentBaseUrl: string, analysisId: string, previewId: string, previewPath: string, token: string): string;
+/**
+ * Canonical `res` claim formula for a report-session page. Returns the literal string
+ * `report-sessions/{analysisId}/{threadId}` with no leading or trailing slash.
+ *
+ * This is the URL sub-path served by the content-server (Caddy) and the token's
+ * authorization boundary — NOT a filesystem sub-path; see the module doc.
+ *
+ * MUST match `fmt.Sprintf("report-sessions/%s/%s", analysisID, threadID)` in
+ * the storage backend's Go `kernel/contenttoken` implementation. Drift is caught by the
+ * shared test vector at `src/__tests__/fixtures/report-session-res.json`.
+ */
+export declare function reportSessionResourceId(analysisId: string, threadId: string): string;
+/**
+ * Build a content-token URL for a report-session page.
+ *
+ * Produces `{contentBaseUrl}/{res}/{pagePath}?t={token}` where `res` is
+ * the output of `reportSessionResourceId(analysisId, threadId)`. The query parameter
+ * name is `t` (matching Caddy's `from_query t` directive). The token is
+ * URL-encoded.
+ *
+ * @param contentBaseUrl - Content server base URL (trailing slash tolerated)
+ * @param analysisId - The analysis ID (authorization boundary)
+ * @param threadId - The report thread ID (one session directory per thread)
+ * @param pagePath - Session-relative path (typically "index.html"). Leading slash tolerated.
+ * @param token - Short-lived content token minted by the storage backend (required)
+ */
+export declare function buildReportSessionUrl(contentBaseUrl: string, analysisId: string, threadId: string, pagePath: string, token: string): string;

package/dist/contracts/content-url.js

@@ -1,21 +1,29 @@
 /**
  * Content URL construction — shared between the frontend and Cortex.
  *
- * The `res` claim formula and URL shape are the canonical TypeScript contract
- * for the content-token preview flow. The storage backend mirrors the formula in Go; both
- * sides are locked by the shared test vector at
- * `src/__tests__/fixtures/preview-res.json`.
+ * The `res` claim formulas and URL shapes are the canonical TypeScript contract
+ * for the content-token flow. The storage backend mirrors each formula in Go; both
+ * sides are locked by the shared test vectors at
+ * `src/__tests__/fixtures/preview-res.json` (previews) and
+ * `src/__tests__/fixtures/report-session-res.json` (report-session pages), each a
+ * byte-identical copy of the storage backend's `kernel/contenttoken/testdata` file.
  *
- * End-to-end contract:
+ * End-to-end contract (previews):
  *   token res claim : "previews/{analysisId}/{previewId}"
  *   URL             : {contentBaseUrl}/previews/{analysisId}/{previewId}/{previewPath}?t={token}
  *   Caddy predicate : request.path.startsWith("/" + res + "/")
  *
+ * End-to-end contract (report-session pages):
+ *   token res claim : "report-sessions/{analysisId}/{threadId}"  (token kind "rs")
+ *   URL             : {contentBaseUrl}/report-sessions/{analysisId}/{threadId}/{pagePath}?t={token}
+ *   Caddy predicate : request.path.startsWith("/" + res + "/")
+ *
  * This is URL space only. On disk a preview lives inside its analysis's workspace tree, at
  * `{resolveWorkspaceRoot(analysisId)}/previews/{previewId}/{previewPath}` (the workspace-layout
- * spec) — the `res` claim carries the analysis id because the URL needs an authorization
- * boundary, whereas the resolved root already identifies the analysis and so does not repeat it.
- * A host that serves previews owns the map between the two.
+ * spec), and a session page at `{resolveWorkspaceRoot(analysisId)}/report-sessions/{threadId}/{pagePath}`
+ * (the report-session-agent spec) — the `res` claim carries the analysis id because the URL needs an
+ * authorization boundary, whereas the resolved root already identifies the analysis and so does not
+ * repeat it. A host that serves either space owns the map between the two.
  *
  * The harness's contracts module owns this TS implementation so both the harness and
  * react-client consume one canonical formula.
@@ -54,3 +62,37 @@ export function buildPreviewUrl(contentBaseUrl, analysisId, previewId, previewPa
     const res = previewResourceId(analysisId, previewId);
     return `${base}/${res}/${path}?t=${encodeURIComponent(token)}`;
 }
+/**
+ * Canonical `res` claim formula for a report-session page. Returns the literal string
+ * `report-sessions/{analysisId}/{threadId}` with no leading or trailing slash.
+ *
+ * This is the URL sub-path served by the content-server (Caddy) and the token's
+ * authorization boundary — NOT a filesystem sub-path; see the module doc.
+ *
+ * MUST match `fmt.Sprintf("report-sessions/%s/%s", analysisID, threadID)` in
+ * the storage backend's Go `kernel/contenttoken` implementation. Drift is caught by the
+ * shared test vector at `src/__tests__/fixtures/report-session-res.json`.
+ */
+export function reportSessionResourceId(analysisId, threadId) {
+    return `report-sessions/${analysisId}/${threadId}`;
+}
+/**
+ * Build a content-token URL for a report-session page.
+ *
+ * Produces `{contentBaseUrl}/{res}/{pagePath}?t={token}` where `res` is
+ * the output of `reportSessionResourceId(analysisId, threadId)`. The query parameter
+ * name is `t` (matching Caddy's `from_query t` directive). The token is
+ * URL-encoded.
+ *
+ * @param contentBaseUrl - Content server base URL (trailing slash tolerated)
+ * @param analysisId - The analysis ID (authorization boundary)
+ * @param threadId - The report thread ID (one session directory per thread)
+ * @param pagePath - Session-relative path (typically "index.html"). Leading slash tolerated.
+ * @param token - Short-lived content token minted by the storage backend (required)
+ */
+export function buildReportSessionUrl(contentBaseUrl, analysisId, threadId, pagePath, token) {
+    const base = contentBaseUrl.replace(/\/+$/, "");
+    const path = pagePath.replace(/^\/+/, "");
+    const res = reportSessionResourceId(analysisId, threadId);
+    return `${base}/${res}/${path}?t=${encodeURIComponent(token)}`;
+}

package/dist/contracts/index.d.ts

@@ -15,4 +15,4 @@ export { CoverageSchema, RowCoverageSchema, EntitySchema, ClaimSupportSchema, Cl
 export type { Coverage, RowCoverage, Entity, EvidenceItem, ClaimSupport, ClaimEvidence, LiabilityBullet, LiabilitySummary, TractabilitySection, ClinicalTrialAttribution, ClinicalTrialRow, ClinicalDevelopment, FailedTrialRow, TrialOutcomeRow, OrganRiskRow, OffTargetRow, RegulatoryActionRow, SafetyFlag, SafetyProfile, OffTissueRow, QualityGateStatus, QualityGates, Derived, Dossier, DossierBody, SectionBlurbKey, TargetAssessmentPhase, TargetAssessmentProgressEvent, } from "./target-dossier.js";
 export { TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentListRowSchema, TargetAssessmentRowSchema, } from "./target-assessment-row.js";
 export type { TargetAssessmentStatus, TargetAssessmentError, TargetAssessmentListRow, TargetAssessmentRow } from "./target-assessment-row.js";
-export { buildPreviewUrl, previewResourceId } from "./content-url.js";
+export { buildPreviewUrl, buildReportSessionUrl, previewResourceId, reportSessionResourceId } from "./content-url.js";

package/dist/contracts/index.js

@@ -5,4 +5,4 @@ export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./part
 export { AnalogyCoverageSchema, AnalogyReportSchema, AnalogyReportErrorSchema, AnalogicalReasonerOutputSchema } from "./analogy-report.js";
 export { CoverageSchema, RowCoverageSchema, EntitySchema, ClaimSupportSchema, ClaimEvidenceSchema, LiabilityBulletSchema, LiabilitySummarySchema, TractabilitySchema, IndicationsSchema, DrugInteractionsSchema, ClinicalTrialAttributionSchema, ClinicalDevelopmentSchema, OrganRiskRowSchema, OffTargetRowSchema, OffTargetPanelSchema, RegulatoryActionRowSchema, SafetyFlagSchema, SafetyProfileSchema, OffTissueRowSchema, OffTissueRiskSchema, ReferenceBiologyShape, EvidenceConflictsSchema, EvidenceTimelineSchema, TranslationalChainSchema, AdditionalEvidenceSchema, DiscoveryTrialsSchema, QualityGateStatusSchema, QualityGatesSchema, DerivedSchema, DossierSchema, DossierBodySchema, isDossier, dossierJsonSchema, SECTION_BLURBS, TargetAssessmentPhaseSchema, TargetAssessmentProgressEventSchema, } from "./target-dossier.js";
 export { TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentListRowSchema, TargetAssessmentRowSchema, } from "./target-assessment-row.js";
-export { buildPreviewUrl, previewResourceId } from "./content-url.js";
+export { buildPreviewUrl, buildReportSessionUrl, previewResourceId, reportSessionResourceId } from "./content-url.js";

package/dist/index.d.ts

@@ -35,6 +35,9 @@ export type { ArtifactManifestEntry } from "./schemas/artifact-manifest.js";
 export type { ProvenanceCollector } from "./provenance/collector.js";
 export { UnavailablePreviewPublisher } from "./tools/report/preview-publisher.js";
 export type { PreviewPublisher, PreviewMintResult } from "./tools/report/preview-publisher.js";
+export { UnavailableSessionPagePublisher } from "./tools/report-session/session-page-publisher.js";
+export type { SessionPagePublisher, SessionPageMintResult } from "./tools/report-session/session-page-publisher.js";
+export type { ResolvePageUrl, SessionPageAccess } from "./tools/report-session/index.js";
 export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 export type { RunLauncher, LaunchOptions } from "./execution/run-launcher.js";
 export { createDbosWorkflowPurger } from "./execution/dbos-workflow-purger.js";

package/dist/index.js

@@ -42,6 +42,11 @@ export { createNoopUsageRecorder } from "./billing/noop-usage-recorder.js";
 export { createNoopArtifactRegistry } from "./execution/noop-artifact-registry.js";
 // Seam: report preview publishing.
 export { UnavailablePreviewPublisher } from "./tools/report/preview-publisher.js";
+// Seam: the hosted view of a report-session page. A managed host serves the URL space
+// `report-sessions/{analysisId}/{threadId}` and mints access through its own publisher,
+// thus the seam belongs on the front door. The URL seam of the eyes rides beside it: a
+// host whose browser cannot reach the workspace tree binds a served URL for the look.
+export { UnavailableSessionPagePublisher } from "./tools/report-session/session-page-publisher.js";
 // Run launching.
 export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 // Seam: workflow-ledger reclamation — cancels and deletes an analysis's rows in

package/dist/runtime/assemble.d.ts

@@ -32,7 +32,7 @@ import { type CitationResolverConfig } from "../citations/resolve.js";
 import type { CitationResolver } from "../citations/types.js";
 import type { AuthContext } from "../auth/types.js";
 import type { ReferenceResolver } from "../report-model/reference-resolver.js";
-import type { ResolvePageAsset } from "../tools/report-session/index.js";
+import type { ResolvePageAsset, ResolvePageUrl, SessionPagePublisher } from "../tools/report-session/index.js";
 /** Registered child sandbox-step callable the parent's child dispatch closes over. */
 export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxStepResult>;
 /**
@@ -132,6 +132,19 @@ export interface CoreRuntimeDeps {
      * materializes them to disk and binds its own lookup here.
      */
     readonly resolveReportPageAsset?: ResolvePageAsset;
+    /**
+     * The hosted view of a report-session page. A managed host that serves the session URL
+     * space binds its publisher here, and the preview tool of the report agent then attaches
+     * the minted URL beside the page path. Absent, the tool attaches nothing and the page
+     * path stays the whole result, which is the whole local path.
+     */
+    readonly sessionPagePublisher?: SessionPagePublisher;
+    /**
+     * The page-URL formation of the report-session eyes. A managed host whose browser cannot
+     * reach the workspace tree binds a resolver that names a served URL for the look. Absent,
+     * the eyes tool navigates through a `file://` URL of the page path.
+     */
+    readonly resolveReportPageUrl?: ResolvePageUrl;
     /**
      * The eyes of a report session — where a browser comes from for one look at the rendered
      * page. A host with no standing sidecar starts a browser for one look. Thus it binds its own

package/dist/runtime/assemble.js

@@ -164,6 +164,8 @@ export function assembleCoreRuntime(deps) {
         makeResolver: makeReportResolver,
         ...(eyes ? { eyes } : {}),
         ...(deps.resolveReportPageAsset ? { resolvePageAsset: deps.resolveReportPageAsset } : {}),
+        ...(deps.sessionPagePublisher ? { sessionPages: deps.sessionPagePublisher } : {}),
+        ...(deps.resolveReportPageUrl ? { resolvePageUrl: deps.resolveReportPageUrl } : {}),
         ...(conversation.logger ? { logger: conversation.logger } : {}),
     });
     // The single registration point for every typed agent. A future thread type's

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

@@ -5,16 +5,18 @@
  * see: the screenshot, the console errors, and the failed requests. The agent reads the picture and the
  * faults, decides, and repairs. The tool never judges, thus it never blocks the loop.
  *
- * The session tree has no URL space, thus the tool navigates to the page file through a `file://` URL. The
- * page lives at `report-sessions/{threadId}/index.html` under the workspace root, which the preview writes.
- * A missed page means that no preview ran, and it is a typed outcome, not a throw.
+ * The composition says which URL one look opens, and the URL seam is that answer. Absent the seam, the tool
+ * navigates to the page file through a `file://` URL. The page lives at `report-sessions/{threadId}/index.html`
+ * under the workspace root, which the preview writes. A missed page means that no preview ran, and it is a
+ * typed outcome, not a throw.
  *
  * The composition says where a browser comes from, and the eyes seam is that answer. One look acquires one
  * lease, and the tool captures against the endpoint of that lease.
  *
- * The `file://` URL resolves on the filesystem of the browser, because the connection is out of process.
- * Thus the browser of a lease must hold the workspace tree of the harness host at the same path. A browser
- * with no such mount reports the page as an unreachable request, and the tool gives back that fault.
+ * The default `file://` URL resolves on the filesystem of the browser, because the connection is out of
+ * process. Thus, absent the URL seam, the browser of a lease must hold the workspace tree of the harness host
+ * at the same path. A browser with no such mount reports the page as an unreachable request, and the tool
+ * gives back that fault. A bound URL seam lifts that constraint, because the browser then opens a served URL.
  *
  * The tool releases the lease after the look. The release runs on a pass and on a failed capture alike. That
  * release is hygiene, and it is not the guarantee against a leak. A process can die between the acquire and
@@ -51,6 +53,15 @@ import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
 import { type Tool } from "../define-tool.js";
 import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
 export type { CapturePage, FailedRequest, PageCapture };
+/**
+ * The URL formation of one look. It maps the page of the thread onto the URL that the browser opens.
+ * A composition whose browser cannot reach the workspace tree binds a resolver that names a served URL.
+ */
+export type ResolvePageUrl = (args: {
+    pagePath: string;
+    analysisId: string;
+    threadId: string;
+}) => Promise<string>;
 /** 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>;
@@ -90,15 +101,17 @@ export type ExaminePageResult = {
  * `resolveWorkspaceRoot` maps the analysis of the call onto its workspace root, thus one singleton tool
  * serves every analysis. `eyes` gives a browser for one look, and the scope of the acquire carries that
  * analysis and its root. `chrome` carries the connection settings of the capture, and the browser that it
- * names must hold the workspace tree at the same path, because the tool navigates to a `file://` URL.
- * `capture` is optional and it replaces the whole transport, thus a test injects a seam that reads no
- * browser.
+ * names must hold the workspace tree at the same path when the tool navigates to a `file://` URL.
+ * `resolvePageUrl` is optional and it replaces that URL, thus a composition whose browser cannot reach the
+ * tree names a served URL instead. `capture` is optional and it replaces the whole transport, thus a test
+ * injects a seam that reads no browser.
  */
 export interface ExaminePageToolDeps {
     readonly gateway: ReportSessionStateGateway;
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     readonly chrome: ChromeConfig;
     readonly eyes?: AcquireEyes;
+    readonly resolvePageUrl?: ResolvePageUrl;
     readonly capture?: CapturePage;
     readonly logger?: Logger;
     /**

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

@@ -5,16 +5,18 @@
  * see: the screenshot, the console errors, and the failed requests. The agent reads the picture and the
  * faults, decides, and repairs. The tool never judges, thus it never blocks the loop.
  *
- * The session tree has no URL space, thus the tool navigates to the page file through a `file://` URL. The
- * page lives at `report-sessions/{threadId}/index.html` under the workspace root, which the preview writes.
- * A missed page means that no preview ran, and it is a typed outcome, not a throw.
+ * The composition says which URL one look opens, and the URL seam is that answer. Absent the seam, the tool
+ * navigates to the page file through a `file://` URL. The page lives at `report-sessions/{threadId}/index.html`
+ * under the workspace root, which the preview writes. A missed page means that no preview ran, and it is a
+ * typed outcome, not a throw.
  *
  * The composition says where a browser comes from, and the eyes seam is that answer. One look acquires one
  * lease, and the tool captures against the endpoint of that lease.
  *
- * The `file://` URL resolves on the filesystem of the browser, because the connection is out of process.
- * Thus the browser of a lease must hold the workspace tree of the harness host at the same path. A browser
- * with no such mount reports the page as an unreachable request, and the tool gives back that fault.
+ * The default `file://` URL resolves on the filesystem of the browser, because the connection is out of
+ * process. Thus, absent the URL seam, the browser of a lease must hold the workspace tree of the harness host
+ * at the same path. A browser with no such mount reports the page as an unreachable request, and the tool
+ * gives back that fault. A bound URL seam lifts that constraint, because the browser then opens a served URL.
  *
  * The tool releases the lease after the look. The release runs on a pass and on a failed capture alike. That
  * release is hygiene, and it is not the guarantee against a leak. A process can die between the acquire and
@@ -270,13 +272,23 @@ 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.
+            let url;
+            try {
+                url = deps.resolvePageUrl !== undefined ? await deps.resolvePageUrl({ pagePath, analysisId, threadId }) : pathToFileURL(pagePath).href;
+            }
+            catch (cause) {
+                logger.warn("the page URL did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });
+                return ok({ outcome: "capture-failed", detail: "the page URL did not resolve" });
+            }
             // The scope of the acquire carries the analysis and the root that this call resolved. Thus a
             // realization that starts a browser mounts the same tree, and it holds no second resolver.
             const looked = await runLook({
                 transport,
                 chrome: deps.chrome,
                 scope: { analysisId, workspaceRoot: root },
-                url: pathToFileURL(pagePath).href,
+                url,
                 acquireMs,
                 releaseMs,
                 logger,

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

@@ -5,8 +5,9 @@
  * 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, type ResolvePageAsset, } from "./preview-report.js";
-export { createExaminePageTool, type CapturePage, type ExaminePageInput, type ExaminePageResult, type ExaminePageToolDeps, type FailedRequest, type PageCapture, } from "./examine-page.js";
+export { createPreviewReportTool, type PreviewReportInput, type PreviewReportResult, type PreviewReportToolDeps, type ResolvePageAsset, type SessionPageAccess, } from "./preview-report.js";
+export { createExaminePageTool, type CapturePage, type ExaminePageInput, type ExaminePageResult, type ExaminePageToolDeps, type FailedRequest, type PageCapture, type ResolvePageUrl, } from "./examine-page.js";
+export { describeSessionPageMintFailure, UnavailableSessionPagePublisher, type SessionPageMintFailure, type SessionPageMintResult, 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/index.js

@@ -7,6 +7,7 @@
  */
 export { createPreviewReportTool, } from "./preview-report.js";
 export { createExaminePageTool, } from "./examine-page.js";
+export { describeSessionPageMintFailure, UnavailableSessionPagePublisher, } from "./session-page-publisher.js";
 export { createRecordVersionTool } from "./record-version.js";
 export { createDeriveTableTool } from "./derive-table.js";
 export { createListPinnedArtifactsTool, } from "./list-artifacts.js";

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

@@ -16,9 +16,11 @@
  * 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.
+ * A hosted view rides the same result. When the composition binds the session-page publisher, the tool
+ * mints one grant after the page lands, and the `rendered` arm carries the URL of the URL space
+ * `report-sessions/{analysisId}/{threadId}` (`contracts/content-url.ts`) beside the path. A refused mint
+ * rides the arm as data, and the page path stays good — a broken grant surface never costs the render. An
+ * unbound publisher changes nothing: the arm carries no access field, and a local host opens the file.
  *
  * Each degraded condition is a typed outcome in the ok channel: a session refusal, a gap list, a resolver
  * absence, an unresolvable root at resolver construction, an unresolved reference, a bridge mismatch, a
@@ -41,12 +43,27 @@ 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";
+import { type SessionPagePublisher } from "./session-page-publisher.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 access grant of the hosted view, as data on the `rendered` arm. A granted mint carries the URL of
+ * the served page and its expiry. A refused mint carries the described refusal, and the page path stays
+ * good.
+ */
+export type SessionPageAccess = {
+    granted: true;
+    url: string;
+    expiresAt: string;
+} | {
+    granted: false;
+    detail: string;
+};
 /**
  * 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.
+ * degraded condition. `rendered` carries the absolute page path, and the access grant of the hosted view
+ * when the composition binds the publisher.
  */
 export type PreviewReportResult = {
     outcome: "refused";
@@ -82,6 +99,7 @@ export type PreviewReportResult = {
 } | {
     outcome: "rendered";
     pagePath: string;
+    access?: SessionPageAccess;
 };
 /**
  * The lookup of the source file of one staged asset. It maps the module specifier of a manifest entry
@@ -99,6 +117,10 @@ export type ResolvePageAsset = (specifier: string) => string;
  * `resolvePageAsset` is optional, and absent it resolves each specifier against the installation of the
  * harness. An embedder that ships the asset bytes packed, for example a compiled single-file binary with no
  * `node_modules` tree, materializes them to disk and binds its own lookup here.
+ *
+ * `sessionPages` is optional, because a local host opens the page path itself. Bound, the tool mints one
+ * grant after the page lands and attaches the URL beside the path. A refused mint rides the `rendered` arm
+ * as data, and it never fails the render.
  */
 export interface PreviewReportToolDeps {
     readonly gateway: ReportSessionStateGateway;
@@ -108,6 +130,7 @@ export interface PreviewReportToolDeps {
     }) => ReferenceResolver;
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     readonly resolvePageAsset?: ResolvePageAsset;
+    readonly sessionPages?: SessionPagePublisher;
     readonly logger?: Logger;
 }
 /**

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

@@ -16,9 +16,11 @@
  * 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.
+ * A hosted view rides the same result. When the composition binds the session-page publisher, the tool
+ * mints one grant after the page lands, and the `rendered` arm carries the URL of the URL space
+ * `report-sessions/{analysisId}/{threadId}` (`contracts/content-url.ts`) beside the path. A refused mint
+ * rides the arm as data, and the page path stays good — a broken grant surface never costs the render. An
+ * unbound publisher changes nothing: the arm carries no access field, and a local host opens the file.
  *
  * Each degraded condition is a typed outcome in the ok channel: a session refusal, a gap list, a resolver
  * absence, an unresolvable root at resolver construction, an unresolved reference, a bridge mismatch, a
@@ -36,6 +38,7 @@ import { extname, join } from "node:path";
 import { relative as relativePosix } from "node:path/posix";
 import { z } from "zod";
 import { reportSessionDir, resolveWorkspacePath } from "../../workspace/paths.js";
+import { buildReportSessionUrl } from "../../contracts/content-url.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
 import { describeFsError, tryFsWrite } from "../../lib/fs-result.js";
 import { defaultErrorFields } from "../../lib/logger.js";
@@ -49,6 +52,7 @@ import { ASSETS_DIR, DEPS_DIR, derivationScriptName, PAGE_ASSETS, stagedSource,
 import { renderReportPage } from "../../report-render/render.js";
 import { defineTool } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
+import { describeSessionPageMintFailure } from "./session-page-publisher.js";
 /** The empty input. The tool renders the current draft of the thread, thus it needs no field. */
 const previewReportInput = z.object({});
 /**
@@ -335,6 +339,36 @@ async function sweepAssets(assetsDir, staged, logger) {
         }
     }
 }
+/**
+ * Mint the hosted view of the page that landed.
+ *
+ * An absent publisher gives no grant, and the arm carries no access field — the page path stays the whole
+ * local contract. A refusal and a thrown 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.
+ */
+async function mintAccess(publisher, analysisId, threadId, logger) {
+    if (publisher === undefined) {
+        return undefined;
+    }
+    let minted;
+    try {
+        minted = await publisher.mintSessionPageAccess(analysisId, threadId);
+    }
+    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,
+    };
+}
 /**
  * Make the render-and-preview tool over the session-state gateway and the render seams.
  *
@@ -438,7 +472,8 @@ export function createPreviewReportTool(deps) {
                 logger.warn("the rendered hash did not stamp", { threadId, analysisId, detail });
                 return ok({ outcome: "stamp-failed", pagePath: written.value, detail });
             }
-            return ok({ outcome: "rendered", pagePath: written.value });
+            const access = await mintAccess(deps.sessionPages, analysisId, threadId, logger);
+            return ok({ outcome: "rendered", pagePath: written.value, ...(access !== undefined ? { access } : {}) });
         },
     });
 }

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

@@ -0,0 +1,55 @@
+/**
+ * SessionPagePublisher — the seam between the report-session path and the hosted view of its page.
+ *
+ * The preview tool writes the page under the session directory and gives back the path. A local host
+ * opens the file, thus it needs no seam. A managed host serves the page over HTTP, and the one thing
+ * that reaches outside the process is the mint of a content-token grant for the URL space
+ * `report-sessions/{analysisId}/{threadId}` (`contracts/content-url.ts`). That mint hides behind this
+ * one method.
+ *
+ * The managed realization owns the grant mint and its client. The local default
+ * (`UnavailableSessionPagePublisher`) returns not-ok, thus the preview tool attaches no URL and the
+ * render still lands — the page path stays the whole local contract.
+ */
+export type SessionPageMintResult = {
+    ok: true;
+    data: {
+        baseUrl: string;
+        token: string;
+        expiresAt: string;
+    };
+} | {
+    ok: false;
+    status?: number;
+    error: {
+        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.
+ *
+ * The failure shape is sparse by design: a realization with no HTTP transport behind it supplies
+ * neither a status nor, necessarily, a message. Naming a field the seam left unset would put the
+ * literal `status=undefined` in front of the model, thus the line carries only what actually arrived.
+ * It lives beside the type because its whole job is to honour that type's optionality.
+ */
+export declare function describeSessionPageMintFailure(failure: SessionPageMintFailure): string;
+export interface SessionPagePublisher {
+    /**
+     * Mint the access grant of one session page. `baseUrl` is the base URL of the content server, with
+     * no res path — the caller spells the whole URL through `buildReportSessionUrl`, thus the formula
+     * lives in the contract and never in a realization.
+     */
+    mintSessionPageAccess(analysisId: string, threadId: string): Promise<SessionPageMintResult>;
+}
+/**
+ * Local default — no hosted view of a session page. Returns not-ok, thus the preview tool carries the
+ * refusal as data and the page path stays the whole result.
+ */
+export declare class UnavailableSessionPagePublisher implements SessionPagePublisher {
+    mintSessionPageAccess(_analysisId: string, _threadId: string): Promise<SessionPageMintResult>;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * SessionPagePublisher — the seam between the report-session path and the hosted view of its page.
+ *
+ * The preview tool writes the page under the session directory and gives back the path. A local host
+ * opens the file, thus it needs no seam. A managed host serves the page over HTTP, and the one thing
+ * that reaches outside the process is the mint of a content-token grant for the URL space
+ * `report-sessions/{analysisId}/{threadId}` (`contracts/content-url.ts`). That mint hides behind this
+ * one method.
+ *
+ * The managed realization owns the grant mint and its client. The local default
+ * (`UnavailableSessionPagePublisher`) returns not-ok, thus the preview tool attaches no URL and the
+ * render still lands — the page path stays the whole local contract.
+ */
+/**
+ * Renders a failed mint as the line an agent reads back from the preview tool.
+ *
+ * The failure shape is sparse by design: a realization with no HTTP transport behind it supplies
+ * neither a status nor, necessarily, a message. Naming a field the seam left unset would put the
+ * literal `status=undefined` in front of the model, thus the line carries only what actually arrived.
+ * It lives beside the type because its whole job is to honour that type's optionality.
+ */
+export function describeSessionPageMintFailure(failure) {
+    const detail = [];
+    if (failure.status !== undefined)
+        detail.push(`status=${failure.status}`);
+    const message = failure.error.message?.trim();
+    if (message)
+        detail.push(message);
+    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
+ * refusal as data and the page path stays the whole result.
+ */
+export class UnavailableSessionPagePublisher {
+    async mintSessionPageAccess(_analysisId, _threadId) {
+        return {
+            ok: false,
+            error: { message: "the hosted view of a session page is unavailable in this environment" },
+        };
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.21.1",
-    "description": "Host-agnostic bioinformatics agent harness \u2014 hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
+    "version": "0.22.0",
+    "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
     "main": "dist/index.js",