@inflexa-ai/harness 0.18.0 → 0.19.1

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

@@ -0,0 +1,72 @@
+/**
+ * The Report Builder agent -- the agent that talks to the user on a report thread.
+ *
+ * `createReportSessionAgent` is the composition root of the report path. It gets
+ * the shared deps one time, and it hands each tool exactly what it needs. The
+ * authoring tools, the preview tool, the eyes tool, and the record tool bind to the
+ * session-state gateway, thus one assembled definition serves every thread, and the
+ * per-session state stays behind the tool boundary.
+ *
+ * The roster is read-only toward the analysis. It holds the workspace read tools,
+ * the workspace search, the run inspection, and the data-profile inspection. It
+ * holds no planner, no run launcher, no working-memory write, and no sandbox
+ * mutate surface. Thus no tool starts a run, and no tool changes an analysis. The
+ * roster omits those tools, and no runtime guard blocks them.
+ *
+ * The definition carries no per-session value. The system prompt composes through
+ * `composeSystemPrompt` with the identity part and the conversational part, the
+ * same composition as the conversation agent. Thus the prompt prefix stays constant
+ * across threads, and the provider cache reuses it.
+ */
+import type { Pool } from "pg";
+import type { AuthContext } from "../auth/types.js";
+import type { AgentDefinition } from "../loop/types.js";
+import type { EmbeddingProvider } from "../providers/types.js";
+import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
+import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
+import type { ChromeConfig } from "../lib/chrome.js";
+import type { Logger } from "../lib/logger.js";
+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";
+/** Canonical agent id -- distinct from the id of the old templating agent. */
+export declare const REPORT_SESSION_AGENT_ID: "report-session";
+/**
+ * The shared dependencies of the report agent. The gateway binds the per-session
+ * state to the thread, thus every tool that touches the state gets the same
+ * gateway. The resolver factory is optional, because a resolver realization can be
+ * absent, and the preview tool and the record tool degrade as data when it is.
+ */
+export interface ReportSessionAgentDeps {
+    /** Model id -- the provenance and metric label. The provider owns the wire model. */
+    readonly model: string;
+    /** Postgres pool -- workspace index, run inspection, and data-profile inspection. */
+    readonly pool: Pool;
+    /** Embedding seam -- workspace semantic search. */
+    readonly embedding: EmbeddingProvider;
+    /** Workspace filesystem read seam -- the four read tools. */
+    readonly workspaceFs: WorkspaceFilesystem;
+    /** Session-state gateway -- the authoring tools, the preview tool, the eyes tool, and the record tool bind to it. */
+    readonly gateway: ReportSessionStateGateway;
+    /** Workspace-root resolution seam -- the preview tool and the eyes tool resolve the page root per call. */
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    /** Append-only version store -- the record tool gates the whole document first, then records one version. */
+    readonly store: ReportVersionStore;
+    /** Thread reader -- the record tool reads the anchor of the report thread. */
+    readonly threads: Pick<ThreadStore, "getThread">;
+    /** Headless-Chrome config -- the eyes tool opens the rendered page. */
+    readonly chrome: ChromeConfig;
+    /**
+     * Reference-resolution factory -- absent until a realization lands; the preview tool and the record tool
+     * degrade as data. The factory binds one analysis, thus a tool makes the resolver over the scope of the call.
+     */
+    readonly makeResolver?: (scope: {
+        analysisId: string;
+        auth: AuthContext;
+    }) => ReferenceResolver;
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
+}
+/** Build the report `AgentDefinition` with every tool bound to its deps. */
+export declare function createReportSessionAgent(deps: ReportSessionAgentDeps): AgentDefinition;

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

@@ -0,0 +1,87 @@
+/**
+ * The Report Builder agent -- the agent that talks to the user on a report thread.
+ *
+ * `createReportSessionAgent` is the composition root of the report path. It gets
+ * the shared deps one time, and it hands each tool exactly what it needs. The
+ * authoring tools, the preview tool, the eyes tool, and the record tool bind to the
+ * session-state gateway, thus one assembled definition serves every thread, and the
+ * per-session state stays behind the tool boundary.
+ *
+ * The roster is read-only toward the analysis. It holds the workspace read tools,
+ * the workspace search, the run inspection, and the data-profile inspection. It
+ * holds no planner, no run launcher, no working-memory write, and no sandbox
+ * mutate surface. Thus no tool starts a run, and no tool changes an analysis. The
+ * roster omits those tools, and no runtime guard blocks them.
+ *
+ * The definition carries no per-session value. The system prompt composes through
+ * `composeSystemPrompt` with the identity part and the conversational part, the
+ * same composition as the conversation agent. Thus the prompt prefix stays constant
+ * across threads, and the provider cache reuses it.
+ */
+import { createReportAuthoringTools } from "../tools/report-authoring/authoring-tools.js";
+import { createExaminePageTool, createPreviewReportTool, createRecordVersionTool } from "../tools/report-session/index.js";
+import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createWorkspaceSearchTool } from "../tools/workspace/index.js";
+import { createInspectDataProfileTool, createInspectRunTool } from "../tools/research/index.js";
+import { reportSessionPrompt } from "../prompts/report-session.js";
+import { composeSystemPrompt } from "./system-prompt.js";
+/** Canonical agent id -- distinct from the id of the old templating agent. */
+export const REPORT_SESSION_AGENT_ID = "report-session";
+/**
+ * Runaway guard. A report turn drives many small tool calls, thus it needs the
+ * same headroom as the conversation agent.
+ */
+const REPORT_SESSION_MAX_ITERATIONS = 50;
+/** 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, makeResolver, logger } = deps;
+    const authoring = createReportAuthoringTools(gateway);
+    const tools = [
+        // The read surface toward the analysis. It roams the tree read-only.
+        createReadFileTool(workspaceFs),
+        createListFilesTool(workspaceFs),
+        createFileStatTool(workspaceFs),
+        createGrepTool(workspaceFs),
+        createWorkspaceSearchTool(pool, embedding),
+        createInspectRunTool(pool),
+        createInspectDataProfileTool(pool),
+        // The composition surface. Each authoring tool binds to the gateway, thus
+        // two threads never share one draft.
+        authoring.add_block,
+        authoring.change_block,
+        authoring.remove_block,
+        authoring.move_block,
+        authoring.set_title,
+        authoring.read_outline,
+        authoring.read_block,
+        authoring.finish_draft,
+        // The render-and-preview tool. It resolves the page root per call.
+        createPreviewReportTool({
+            gateway,
+            resolveWorkspaceRoot,
+            ...(makeResolver ? { makeResolver } : {}),
+            ...(logger ? { logger } : {}),
+        }),
+        // The eyes tool. It opens the rendered page in headless Chrome.
+        createExaminePageTool({
+            gateway,
+            resolveWorkspaceRoot,
+            chrome,
+            ...(logger ? { logger } : {}),
+        }),
+        // The record tool. It gates the whole document, then records one version.
+        createRecordVersionTool({
+            gateway,
+            store,
+            threads,
+            ...(makeResolver ? { makeResolver } : {}),
+            ...(logger ? { logger } : {}),
+        }),
+    ];
+    return {
+        id: REPORT_SESSION_AGENT_ID,
+        systemPrompt: composeSystemPrompt(reportSessionPrompt, { identity: true, conversational: true }),
+        model,
+        tools,
+        maxIterations: REPORT_SESSION_MAX_ITERATIONS,
+    };
+}

package/dist/app/report-session-runtime.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The report session-state runtime -- the durable realization of the session-state
+ * gateway, and the idempotent operation that anchors one report session.
+ *
+ * The runtime binds three parts: the session-state store, the thread store, and
+ * the pin. The tool layer speaks the gateway, and the gateway speaks a plain
+ * discriminated value. Thus the neverthrow of the store stays inside this module,
+ * and it never crosses the tool boundary.
+ *
+ * `ensureSessionState` makes sure that the row of a thread exists. The first run
+ * resolves the analysis of the thread, pins the snapshot, and writes the row. A
+ * later run reads the row and pins nothing. The store insert-if-absent keeps two
+ * concurrent first runs to one row. A pin failure writes no row and returns as
+ * typed data, thus a later run pins again.
+ *
+ * The gateway `load` runs the same operation, thus a tool call never arrives
+ * before the state exists. A fresh row holds the snapshot and no document yet.
+ * Thus `load` gives the empty draft with the stored snapshot, because the pin
+ * writes the snapshot first and the document lands later.
+ *
+ * A store fault, an absent thread, and a pin failure each ride the failed arm
+ * with a short detail. The diagnostic goes to the injected `Logger`, never to the
+ * detail alone.
+ *
+ * The gateway load separates a permanent condition from a transient one. An absent
+ * thread and a wrong thread type are permanent, and a store or pin fault is
+ * transient. The persist is a compare-and-swap against the prior document that the
+ * load read, thus two concurrent turns cannot both land.
+ */
+import type { Pool } from "pg";
+import type { Logger } from "../lib/logger.js";
+import { type ReportSessionState as StoredSessionState } from "../state/report-session-state.js";
+import type { ReportSessionStateGateway } from "../tools/report-authoring/authoring-tools.js";
+/**
+ * How a failed anchor ends. `absent-thread` and `wrong-thread-type` are permanent
+ * conditions, and `unavailable` is a transient store or pin fault. The gateway load
+ * carries the distinction, thus the tool tells a permanent refusal from a transient one.
+ */
+export type EnsureFailureKind = "absent-thread" | "wrong-thread-type" | "unavailable";
+/**
+ * The outcome of the anchor operation. `ready` carries the durable row, whose
+ * document is `null` until the first document lands. `failed` names the cause as a
+ * short detail and a kind, and the runtime logs the diagnostic beside it.
+ */
+export type EnsureSessionStateResult = {
+    outcome: "ready";
+    state: StoredSessionState;
+} | {
+    outcome: "failed";
+    kind: EnsureFailureKind;
+    detail: string;
+};
+export interface ReportSessionRuntimeDeps {
+    readonly pool: Pool;
+    readonly logger?: Logger;
+}
+/**
+ * The report session-state runtime. The gateway serves the authoring tools, and
+ * `ensureSessionState` anchors the session. The serving path of a report turn runs
+ * `ensureSessionState` at the turn start, and the gateway `load` runs it too, thus
+ * a tool call cannot arrive before the state exists.
+ */
+export interface ReportSessionRuntime {
+    readonly gateway: ReportSessionStateGateway;
+    ensureSessionState(threadId: string): Promise<EnsureSessionStateResult>;
+}
+/**
+ * Build the report session-state runtime bound to a Postgres pool. The factory
+ * closure captures the pool and constructs the session-state store and the thread
+ * store from it, the same way the chat-turn preparation does.
+ */
+export declare function createReportSessionRuntime(deps: ReportSessionRuntimeDeps): ReportSessionRuntime;

package/dist/app/report-session-runtime.js

@@ -0,0 +1,183 @@
+/**
+ * The report session-state runtime -- the durable realization of the session-state
+ * gateway, and the idempotent operation that anchors one report session.
+ *
+ * The runtime binds three parts: the session-state store, the thread store, and
+ * the pin. The tool layer speaks the gateway, and the gateway speaks a plain
+ * discriminated value. Thus the neverthrow of the store stays inside this module,
+ * and it never crosses the tool boundary.
+ *
+ * `ensureSessionState` makes sure that the row of a thread exists. The first run
+ * resolves the analysis of the thread, pins the snapshot, and writes the row. A
+ * later run reads the row and pins nothing. The store insert-if-absent keeps two
+ * concurrent first runs to one row. A pin failure writes no row and returns as
+ * typed data, thus a later run pins again.
+ *
+ * The gateway `load` runs the same operation, thus a tool call never arrives
+ * before the state exists. A fresh row holds the snapshot and no document yet.
+ * Thus `load` gives the empty draft with the stored snapshot, because the pin
+ * writes the snapshot first and the document lands later.
+ *
+ * A store fault, an absent thread, and a pin failure each ride the failed arm
+ * with a short detail. The diagnostic goes to the injected `Logger`, never to the
+ * detail alone.
+ *
+ * The gateway load separates a permanent condition from a transient one. An absent
+ * thread and a wrong thread type are permanent, and a store or pin fault is
+ * transient. The persist is a compare-and-swap against the prior document that the
+ * load read, thus two concurrent turns cannot both land.
+ */
+import { createNoopLogger } from "../lib/console-logger.js";
+import { describeDbError } from "../lib/db-result.js";
+import { createThreadStore } from "../memory/thread-store.js";
+import { pinReportSnapshot } from "../report-model/pin-snapshot.js";
+import { createReportSessionStateStore } from "../state/report-session-state.js";
+/** The empty draft of a fresh session. The pin writes the snapshot first, thus the document is empty here. */
+const EMPTY_DRAFT = { title: "", sections: [] };
+/**
+ * Build the report session-state runtime bound to a Postgres pool. The factory
+ * closure captures the pool and constructs the session-state store and the thread
+ * store from it, the same way the chat-turn preparation does.
+ */
+export function createReportSessionRuntime(deps) {
+    const { pool } = deps;
+    const log = (deps.logger ?? createNoopLogger()).named("report-session-runtime");
+    const store = createReportSessionStateStore({ pool, logger: deps.logger });
+    const threads = createThreadStore(pool);
+    /**
+     * A store read or write fault, as a failed outcome. `corrupt_session_state`
+     * names the part that cannot parse. A `DbError` carries its cause to the log.
+     * The identifiers ride as structured fields, never in the message.
+     */
+    function storeFault(threadId, error) {
+        if (error.type === "corrupt_session_state") {
+            log.error("the stored session state cannot parse", { threadId, part: error.part });
+            return { outcome: "failed", kind: "unavailable", detail: `the stored ${error.part} of the session state cannot parse` };
+        }
+        log.error("the session-state store failed", { threadId, ...log.errorFields(error.cause) });
+        return { outcome: "failed", kind: "unavailable", detail: describeDbError(error) };
+    }
+    /**
+     * Pin the snapshot and write the row. A pin failure writes no row, thus a
+     * later run pins again. The write is insert-if-absent, thus two concurrent
+     * first runs make one row and both read the winner back.
+     */
+    async function pinAndWrite(threadId, analysisId) {
+        const pinned = await pinReportSnapshot(pool, analysisId);
+        if (pinned.isErr()) {
+            log.error("the snapshot pin failed", { threadId, analysisId, ...log.errorFields(pinned.error.cause) });
+            return { outcome: "failed", kind: "unavailable", detail: "the artifact ledger read failed" };
+        }
+        const written = await store.writeSnapshot({ threadId, analysisId, snapshot: pinned.value });
+        return written.match((row) => ({ outcome: "ready", state: row }), (error) => storeFault(threadId, error));
+    }
+    async function ensureSessionState(threadId) {
+        const read = await store.readState(threadId);
+        if (read.isErr()) {
+            return storeFault(threadId, read.error);
+        }
+        if (read.value !== null) {
+            // The row exists, thus the anchor holds and the pin stays single.
+            return { outcome: "ready", state: read.value };
+        }
+        const thread = await threads.getThread(threadId);
+        if (thread.isErr()) {
+            log.error("the thread read failed", { threadId, ...log.errorFields(thread.error.cause) });
+            return { outcome: "failed", kind: "unavailable", detail: describeDbError(thread.error) };
+        }
+        if (thread.value === null) {
+            // The pin needs the analysis of the thread. An absent thread names none, and
+            // the absence is a permanent condition.
+            log.error("the thread resolves to no analysis", { threadId });
+            return { outcome: "failed", kind: "absent-thread", detail: "the thread names no analysis" };
+        }
+        if (thread.value.threadType !== "report") {
+            // The session anchors a report thread only. A conversation thread carries no report session,
+            // thus a wrong type writes no row and the detail names the type. The wrong type is permanent.
+            log.error("the thread is not a report thread", { threadId, threadType: thread.value.threadType });
+            return { outcome: "failed", kind: "wrong-thread-type", detail: `the thread is a ${thread.value.threadType} thread, not a report thread` };
+        }
+        return pinAndWrite(threadId, thread.value.analysisId);
+    }
+    /**
+     * Map the durable row onto the gateway load. A fresh row holds the snapshot and
+     * no document, thus the load gives the empty draft. The found load carries the
+     * stored analysis and the prior document as the concurrency token. A row with no
+     * snapshot cannot serve a tool, because the pin writes the snapshot first.
+     */
+    function toLoad(state) {
+        if (state.snapshot === null) {
+            log.error("the session-state row holds no snapshot", { threadId: state.threadId });
+            return { outcome: "failed", detail: "the session state holds no snapshot" };
+        }
+        return {
+            outcome: "found",
+            state: { document: state.document ?? EMPTY_DRAFT, snapshot: state.snapshot },
+            analysisId: state.analysisId,
+            token: state.document,
+            seenDocumentHash: state.seenDocumentHash,
+        };
+    }
+    const gateway = {
+        async load(threadId) {
+            const ensured = await ensureSessionState(threadId);
+            if (ensured.outcome === "failed") {
+                switch (ensured.kind) {
+                    case "absent-thread":
+                        return { outcome: "absent" };
+                    case "wrong-thread-type":
+                        return { outcome: "wrong-type", detail: ensured.detail };
+                    case "unavailable":
+                        return { outcome: "failed", detail: ensured.detail };
+                }
+            }
+            return toLoad(ensured.state);
+        },
+        async persist(threadId, document, expected) {
+            const result = await store.persistDocument({ threadId, document, expected });
+            return result.match((outcome) => {
+                switch (outcome) {
+                    case "persisted":
+                        return { outcome: "persisted" };
+                    case "conflict":
+                        // A concurrent turn landed first. The turn refuses and reads the state again.
+                        return { outcome: "conflict" };
+                    case "absent":
+                        // The pin writes the row first. A persist that finds no row means the
+                        // pin-first invariant broke.
+                        log.error("the session-state persist matched no row", { threadId });
+                        return { outcome: "failed", detail: "no report session state row exists to persist the document" };
+                }
+            }, (error) => {
+                log.error("the session-state persist failed", { threadId, ...log.errorFields(error.cause) });
+                return { outcome: "failed", detail: describeDbError(error) };
+            });
+        },
+        async stampRendered(threadId, hash) {
+            const result = await store.stampRendered(threadId, hash);
+            return result.match((outcome) => (outcome === "stamped" ? { outcome: "stamped" } : { outcome: "absent" }), (error) => {
+                log.error("the rendered-hash stamp failed", { threadId, ...log.errorFields(error.cause) });
+                return { outcome: "failed", detail: describeDbError(error) };
+            });
+        },
+        async stampSeen(threadId) {
+            const result = await store.stampSeen(threadId);
+            return result.match((outcome) => {
+                switch (outcome) {
+                    case "stamped":
+                        return { outcome: "stamped" };
+                    case "no-rendered":
+                        // The row holds no rendered hash, thus no preview stamped one and the copy found
+                        // none. The eyes direct a new preview from this arm.
+                        return { outcome: "no-rendered" };
+                    case "absent":
+                        return { outcome: "absent" };
+                }
+            }, (error) => {
+                log.error("the seen-hash stamp failed", { threadId, ...log.errorFields(error.cause) });
+                return { outcome: "failed", detail: describeDbError(error) };
+            });
+        },
+    };
+    return { gateway, ensureSessionState };
+}

package/dist/app/spawn-report-session.d.ts

@@ -18,10 +18,19 @@
  * A conversation thread id comes from the host UI. But the spawn is a harness
  * operation with no UI in front of it. Thus it mints a `randomUUID` and returns
  * the full row. A managed deployment gets the same behavior with no host code.
+ *
+ * The spawn also gates on the eyes of the composition. A report session records
+ * a version only after a look at the rendered page, and only a browser can look.
+ * Thus a composition with no browser and no injected capture seam can author a
+ * draft that no gate ever accepts. The spawn refuses that session before it
+ * writes a row, because a dead-end thread is worse than a refusal that names the
+ * absent capability.
  */
 import { type ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
 import type { DbError } from "../lib/db-result.js";
+import { type ChromeConfig } from "../lib/chrome.js";
+import type { CapturePage } from "../lib/page-capture.js";
 import { type Thread, type ThreadInputError, type ThreadPage, type ThreadType } from "../memory/thread-store.js";
 /**
  * A spawn the operation refuses before it writes a row. Distinct from
@@ -34,9 +43,15 @@ import { type Thread, type ThreadInputError, type ThreadPage, type ThreadType }
  * state is not permitted. `parent_not_a_conversation` keeps the tree flat: a
  * report session cannot spawn another. `empty_parent_transcript` refuses a
  * report on a parent that holds no messages, because such a report reports
- * nothing.
+ * nothing. `no_browser` refuses every spawn under a composition that gives no
+ * eyes, and it carries the line that explains the absent capability.
  */
 export type SpawnRefusal = {
+    readonly type: "no_browser";
+    readonly op: string;
+    readonly parentThreadId: string;
+    readonly detail: string;
+} | {
     readonly type: "parent_not_found";
     readonly op: string;
     readonly parentThreadId: string;
@@ -57,6 +72,18 @@ export interface ReportSessionPaging {
 }
 export interface ReportSessionSpawnDeps {
     readonly pool: Pool;
+    /**
+     * The chrome config that the same composition gives to the eyes tool. The
+     * spawn reads only whether it names a browser, thus the spawn and the tool
+     * decide the availability of the eyes from one value.
+     */
+    readonly chrome: ChromeConfig;
+    /**
+     * The capture seam that the same composition gives to the eyes tool. A
+     * present seam is a route to a look with no browser endpoint, thus it
+     * satisfies the gate on its own.
+     */
+    readonly capture?: CapturePage;
 }
 export interface ReportSessionSpawn {
     /**
@@ -64,10 +91,10 @@ export interface ReportSessionSpawn {
      * The child takes the analysis of the parent, the parent thread id, and the
      * anchor — the parent's latest `messages.seq` at this moment.
      *
-     * Refused with a `SpawnRefusal`, no row written: an absent or archived
-     * parent, a parent that is not a conversation, and a parent with no
-     * messages. A store refusal (`DbError`, `ThreadInputError`) passes through
-     * unchanged.
+     * Refused with a `SpawnRefusal`, no row written: a composition with no
+     * eyes, an absent or archived parent, a parent that is not a conversation,
+     * and a parent with no messages. A store refusal (`DbError`,
+     * `ThreadInputError`) passes through unchanged.
      */
     spawnReportSession(parentThreadId: string): ResultAsync<Thread, SpawnRefusal | DbError | ThreadInputError>;
     /**

package/dist/app/spawn-report-session.js

@@ -18,13 +18,23 @@
  * A conversation thread id comes from the host UI. But the spawn is a harness
  * operation with no UI in front of it. Thus it mints a `randomUUID` and returns
  * the full row. A managed deployment gets the same behavior with no host code.
+ *
+ * The spawn also gates on the eyes of the composition. A report session records
+ * a version only after a look at the rendered page, and only a browser can look.
+ * Thus a composition with no browser and no injected capture seam can author a
+ * draft that no gate ever accepts. The spawn refuses that session before it
+ * writes a row, because a dead-end thread is worse than a refusal that names the
+ * absent capability.
  */
 import { randomUUID } from "node:crypto";
 import { errAsync } from "neverthrow";
+import { hasBrowserUrl } from "../lib/chrome.js";
 import { createThreadHistory } from "../memory/thread-history.js";
 import { createThreadStore } from "../memory/thread-store.js";
 const _assertDomainError = true;
 const OP = "spawn-report-session";
+/** The line that the caller reads when the composition gives no eyes. */
+const NO_BROWSER_DETAIL = "the composition gives no browser, thus a report session can never record a version";
 /**
  * Compose the child title. N counts the existing report children of the parent
  * plus one. A parent with no title yields `Report N` alone, because the seed of
@@ -43,7 +53,16 @@ export function createReportSessionSpawn(deps) {
     const { pool } = deps;
     const store = createThreadStore(pool);
     const history = createThreadHistory(pool);
+    // The eyes of the composition are fixed at construction, thus the gate reads
+    // one boolean and never a live probe of the sidecar.
+    const eyesAvailable = deps.capture !== undefined || hasBrowserUrl(deps.chrome);
     function spawnReportSession(parentThreadId) {
+        // The gate runs before the parent read. A session with no route to a look
+        // reaches the record gate and refuses there forever, thus the spawn is the
+        // one honest place to say so.
+        if (!eyesAvailable) {
+            return errAsync({ type: "no_browser", op: OP, parentThreadId, detail: NO_BROWSER_DETAIL });
+        }
         return store.getThread(parentThreadId).andThen((parent) => {
             // An absent parent and an archived one arrive the same way — `getThread`
             // filters the tombstone — and both refuse as `parent_not_found`.

package/dist/config/environment-stores.d.ts

@@ -18,17 +18,22 @@
  * one. Neither store is ever written through these paths.
  *
  * Both are optional, and absence is a NORMAL state rather than an error: an
- * omitted path makes its tool report the store as unavailable or unknown, which
- * is a truthful answer an agent can act on. Absence must never be reported as a
- * failure, and never papered over with a guessed path.
+ * omitted path falls back to the store's container mountpoint — correct for a
+ * host whose own process sees the store the way a sandbox does, and harmless for
+ * one that does not, because every consumer stats the root before it reports
+ * anything. A host with nothing mounted there gets the same "unavailable" or
+ * "unknown" answer an omitted path has always produced, so the fallback can no
+ * more invent a store than an explicit path can. Set a path only to name a
+ * location the container mountpoint does not describe; absence must never be
+ * reported as a failure.
  */
 export interface EnvironmentStorePaths {
     /**
      * Host path of the reference store — the same bytes sandboxes mount at
-     * `/mnt/refs`. Omit when no store is provisioned; reference discovery then
-     * reports the store as unavailable. Note that an installed store reads as
-     * absent if this is omitted, which is indistinguishable to an agent from
-     * having no data — so omit it only when there is genuinely nothing staged.
+     * `/mnt/refs`. Omit when the host's own process sees the store at that same
+     * path, as a K8s pod holding the ref-store PVC does; set it when the host
+     * reads the store somewhere else, as a native process bind-mounting a host
+     * directory into Docker does.
      */
     readonly refStorePath?: string;
     /**

package/dist/config/resource-limits.d.ts

@@ -1,8 +1,11 @@
 /**
- * Resource limits — ported from orchestrator/src/config/resource-limits.ts.
+ * Resource limits — validates sandbox resource requests against cluster
+ * maximums.
  *
- * Validates sandbox resource requests against cluster maximums.
- * Used by K8sSandbox.
+ * The ceilings themselves are the embedder's: they arrive as
+ * `SandboxClientConfig.resourceLimits` and as the `resourcePolicy` this module
+ * validates. Nothing here reads the environment, so a host keeps one validated
+ * view of its own configuration rather than two that can disagree.
  */
 import { z } from "zod";
 export declare const GpuSpecSchema: z.ZodObject<{
@@ -47,13 +50,6 @@ export declare const DEFAULT_SANDBOX_MAX_STEPS = 75;
 export declare class ResourceLimitsConfigError extends Error {
     constructor(message: string);
 }
-/**
- * Load resource limits from environment variables.
- *
- * Required: SANDBOX_MAX_CPU, SANDBOX_MAX_MEMORY_GB, SANDBOX_MAX_GPU_COUNT
- * @throws ResourceLimitsConfigError if configuration is invalid
- */
-export declare function loadResourceLimits(): ResourceLimits;
 /**
  * Validate an embedder-supplied resource policy.
  *

package/dist/config/resource-limits.js

@@ -1,8 +1,11 @@
 /**
- * Resource limits — ported from orchestrator/src/config/resource-limits.ts.
+ * Resource limits — validates sandbox resource requests against cluster
+ * maximums.
  *
- * Validates sandbox resource requests against cluster maximums.
- * Used by K8sSandbox.
+ * The ceilings themselves are the embedder's: they arrive as
+ * `SandboxClientConfig.resourceLimits` and as the `resourcePolicy` this module
+ * validates. Nothing here reads the environment, so a host keeps one validated
+ * view of its own configuration rather than two that can disagree.
  */
 import { z } from "zod";
 // ── Schemas ─────────────────────────────────────────────────────────
@@ -38,47 +41,6 @@ export class ResourceLimitsConfigError extends Error {
         this.name = "ResourceLimitsConfigError";
     }
 }
-// ── Parsing ─────────────────────────────────────────────────────────
-function parsePositiveNumber(name, value) {
-    if (!value) {
-        throw new ResourceLimitsConfigError(`${name} environment variable is required`);
-    }
-    const num = Number(value);
-    if (isNaN(num) || num <= 0) {
-        throw new ResourceLimitsConfigError(`${name} must be a positive number, got: ${value}`);
-    }
-    return num;
-}
-function parseNonNegativeInt(name, value) {
-    if (!value) {
-        throw new ResourceLimitsConfigError(`${name} environment variable is required`);
-    }
-    const num = Number(value);
-    if (isNaN(num) || num < 0) {
-        throw new ResourceLimitsConfigError(`${name} must be a non-negative number, got: ${value}`);
-    }
-    if (!Number.isInteger(num)) {
-        throw new ResourceLimitsConfigError(`${name} must be an integer, got: ${value}`);
-    }
-    return num;
-}
-/**
- * Load resource limits from environment variables.
- *
- * Required: SANDBOX_MAX_CPU, SANDBOX_MAX_MEMORY_GB, SANDBOX_MAX_GPU_COUNT
- * @throws ResourceLimitsConfigError if configuration is invalid
- */
-export function loadResourceLimits() {
-    const maxCpu = parsePositiveNumber("SANDBOX_MAX_CPU", process.env.SANDBOX_MAX_CPU);
-    const maxMemoryGb = parsePositiveNumber("SANDBOX_MAX_MEMORY_GB", process.env.SANDBOX_MAX_MEMORY_GB);
-    const maxGpuCount = parseNonNegativeInt("SANDBOX_MAX_GPU_COUNT", process.env.SANDBOX_MAX_GPU_COUNT);
-    const limits = { maxCpu, maxMemoryGb, maxGpuCount };
-    const result = ResourceLimitsSchema.safeParse(limits);
-    if (!result.success) {
-        throw new ResourceLimitsConfigError(`Invalid resource limits configuration: ${result.error.message}`);
-    }
-    return result.data;
-}
 /**
  * Validate an embedder-supplied resource policy.
  *