@inflexa-ai/harness 0.19.2 → 0.21.0

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

@@ -0,0 +1,115 @@
+/**
+ * The tool that starts a report session from a conversation.
+ *
+ * The tool is the one report path of the conversation agent. It reads the parent
+ * thread from the scope of the call, thus the agent cannot name a different
+ * conversation. It carries the intent brief of the ask, and the spawn seeds the
+ * context of the child with that brief.
+ *
+ * The order of the checks is fixed. The eyes gate runs first. A composition
+ * that names no route to a look is a permanent condition, and the advice is
+ * transient state. The advice runs next. At one user turn or less of the parent
+ * past the anchor of the newest report child, the tool starts nothing and it
+ * names that child. The spawn runs last.
+ *
+ * Each degraded condition is a typed outcome in the ok channel: a scope with no
+ * thread id, a composition with no eyes, the advice, each refusal of the spawn,
+ * and a store fault. The tool never throws for one of them.
+ */
+import type { Pool } from "pg";
+import { z } from "zod";
+import type { EnsureSessionStateResult } from "../app/report-session-runtime.js";
+import type { ChromeConfig } from "../lib/chrome.js";
+import type { AcquireEyes } from "../lib/eyes.js";
+import type { Logger } from "../lib/logger.js";
+import type { ThreadType } from "../memory/thread-store.js";
+import { type Tool } from "./define-tool.js";
+/**
+ * The brief of the ask, plus the one override of the advice.
+ *
+ * Each brief field is short prose. No field names a path, a dataset, or a
+ * format, because the report session reads those from the workspace itself.
+ */
+declare const startReportSessionInput: z.ZodObject<{
+    objective: z.ZodString;
+    audience: z.ZodString;
+    angle: z.ZodString;
+    exclusions: z.ZodOptional<z.ZodString>;
+    openQuestions: z.ZodOptional<z.ZodString>;
+    newSessionAnyway: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type StartReportSessionInput = z.infer<typeof startReportSessionInput>;
+/**
+ * The typed outcome of the tool. Each arm is ok-channel data, thus the tool
+ * never throws for a degraded condition.
+ *
+ * `started` and `existing-session` name a report thread. `refused` names a call
+ * whose scope carries no conversation thread. The four refusals of the spawn
+ * keep their own names, thus the agent reads one reason from the spawn and from
+ * the tool alike. `failed` is a store fault, and it carries a short line.
+ */
+export type StartReportSessionResult = {
+    outcome: "started";
+    threadId: string;
+    title: string | null;
+} | {
+    outcome: "existing-session";
+    threadId: string;
+    title: string | null;
+} | {
+    outcome: "refused";
+    detail: string;
+} | {
+    outcome: "no_browser";
+    detail: string;
+} | {
+    outcome: "parent_not_found";
+} | {
+    outcome: "parent_not_a_conversation";
+    threadType: ThreadType;
+} | {
+    outcome: "empty_parent_transcript";
+} | {
+    outcome: "failed";
+    detail: string;
+};
+/**
+ * The construction deps of the tool.
+ *
+ * The fields build the spawn operation inside the factory. Thus one singleton
+ * tool serves every conversation, and it reads the parent from the scope of each
+ * call.
+ *
+ * Two of the fields name a route to a look at the rendered page: `eyes` and a
+ * `chrome` config that names a browser. The tool binds no capture seam. That
+ * seam replaces the transport of the eyes tool, and the tool here never looks at
+ * a page. A composition that binds a capture seam straight to the spawn still
+ * opens the gate of that spawn.
+ */
+export interface StartReportSessionToolDeps {
+    readonly pool: Pool;
+    readonly chrome: ChromeConfig;
+    /**
+     * The eyes seam of the composition. A bound seam gives a browser for one
+     * look, thus the spawn accepts a session with no configured endpoint. The
+     * tool passes the seam to the spawn, and it acquires no lease.
+     */
+    readonly eyes?: AcquireEyes;
+    /**
+     * The anchor operation of the report session runtime, which the spawn runs
+     * after the seed of the child lands. The composition binds it, thus the tool
+     * carries no stale value of its own.
+     */
+    readonly anchorSession?: (threadId: string) => Promise<EnsureSessionStateResult>;
+    readonly logger?: Logger;
+}
+/**
+ * Make the tool that starts a report session, over one Postgres pool and the
+ * eyes of the composition.
+ *
+ * The factory builds the deps of the spawn one time. The spawn and the gate of
+ * the tool read that one value, thus the two gates cannot disagree. The tool
+ * holds no per-conversation value.
+ */
+export declare function createStartReportSessionTool(deps: StartReportSessionToolDeps): Tool<StartReportSessionInput, StartReportSessionResult>;
+export {};

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

@@ -0,0 +1,179 @@
+/**
+ * The tool that starts a report session from a conversation.
+ *
+ * The tool is the one report path of the conversation agent. It reads the parent
+ * thread from the scope of the call, thus the agent cannot name a different
+ * conversation. It carries the intent brief of the ask, and the spawn seeds the
+ * context of the child with that brief.
+ *
+ * The order of the checks is fixed. The eyes gate runs first. A composition
+ * that names no route to a look is a permanent condition, and the advice is
+ * transient state. The advice runs next. At one user turn or less of the parent
+ * past the anchor of the newest report child, the tool starts nothing and it
+ * names that child. The spawn runs last.
+ *
+ * Each degraded condition is a typed outcome in the ok channel: a scope with no
+ * thread id, a composition with no eyes, the advice, each refusal of the spawn,
+ * and a store fault. The tool never throws for one of them.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { compositionHasEyes, createReportSessionSpawn } from "../app/spawn-report-session.js";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { describeDbError } from "../lib/db-result.js";
+import { defineTool } from "./define-tool.js";
+/**
+ * The character bound of each brief field. The whole brief lands in one durable
+ * message row, thus the schema holds no unbounded string out of the store.
+ *
+ * The description caps the brief at approximately 2000 tokens, and a token is
+ * about four characters. Thus the five bounds sum to 8000 characters, and the
+ * widest brief that the schema admits still meets the cap that the agent reads.
+ *
+ * The share of each field follows its role. `audience` names one reader, thus a
+ * phrase is enough. `objective` and `angle` carry a sentence or two. Each
+ * optional field carries a list of items, thus it takes the largest share.
+ */
+const BRIEF_MAX = {
+    objective: 1500,
+    audience: 200,
+    angle: 1500,
+    exclusions: 2400,
+    openQuestions: 2400,
+};
+/**
+ * The brief of the ask, plus the one override of the advice.
+ *
+ * Each brief field is short prose. No field names a path, a dataset, or a
+ * format, because the report session reads those from the workspace itself.
+ */
+const startReportSessionInput = z.object({
+    objective: z.string().min(1).max(BRIEF_MAX.objective).describe("The question that the report must answer."),
+    audience: z.string().min(1).max(BRIEF_MAX.audience).describe("The reader of the report."),
+    angle: z.string().min(1).max(BRIEF_MAX.angle).describe("The line that the report takes through the evidence."),
+    exclusions: z.string().max(BRIEF_MAX.exclusions).optional().describe("The material that the report must leave out."),
+    openQuestions: z.string().max(BRIEF_MAX.openQuestions).optional().describe("The points that the user did not decide yet."),
+    newSessionAnyway: z
+        .boolean()
+        .optional()
+        .describe("Set it to true to start a new session when the conversation holds no user turn of new work after the last report session. The default is false."),
+});
+/** The line that a call reads when the scope names no conversation thread. */
+const NO_THREAD_SCOPE_DETAIL = "the scope of the call names no conversation thread, thus the tool cannot start a child session";
+/** The line that a call reads when the thread store refuses the shape of the child. */
+const STORE_REFUSED_DETAIL = "the thread store refused the shape of the child session";
+/**
+ * Map a fault of the spawn onto its arm. The switch is exhaustive over the three
+ * error unions, thus a new variant fails the build instead of falling into one
+ * arm in silence.
+ */
+function toOutcome(fault) {
+    switch (fault.type) {
+        case "no_browser":
+            return { outcome: "no_browser", detail: fault.detail };
+        case "parent_not_found":
+            return { outcome: "parent_not_found" };
+        case "parent_not_a_conversation":
+            return { outcome: "parent_not_a_conversation", threadType: fault.threadType };
+        case "empty_parent_transcript":
+            return { outcome: "empty_parent_transcript" };
+        case "query_failed":
+        case "mutation_failed":
+        case "connection_failed":
+        case "constraint_violation":
+            return { outcome: "failed", detail: describeDbError(fault) };
+        case "parent_analysis_mismatch":
+        case "parent_anchor_unpaired":
+        case "unknown_thread_type":
+            return { outcome: "failed", detail: STORE_REFUSED_DETAIL };
+    }
+}
+/** The cause of a fault, or `undefined` for a fault that carries none. */
+function causeOf(fault) {
+    return "cause" in fault ? fault.cause : undefined;
+}
+/**
+ * Make the tool that starts a report session, over one Postgres pool and the
+ * eyes of the composition.
+ *
+ * The factory builds the deps of the spawn one time. The spawn and the gate of
+ * the tool read that one value, thus the two gates cannot disagree. The tool
+ * holds no per-conversation value.
+ */
+export function createStartReportSessionTool(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("start-report-session");
+    const spawnDeps = {
+        pool: deps.pool,
+        chrome: deps.chrome,
+        ...(deps.eyes ? { eyes: deps.eyes } : {}),
+        ...(deps.anchorSession ? { anchorSession: deps.anchorSession } : {}),
+        ...(deps.logger ? { logger: deps.logger } : {}),
+    };
+    const spawn = createReportSessionSpawn(spawnDeps);
+    // The gate reads the routes of the very spawn below, thus the two answers
+    // come from one value. The routes are fixed at construction, thus the gate
+    // reads one boolean and never a live probe of the sidecar.
+    const eyesAvailable = compositionHasEyes(spawnDeps);
+    return defineTool({
+        id: "start_report_session",
+        description: "Start an interactive report session as a child of this conversation. " +
+            "The user composes the report in that chat, with the report agent. " +
+            "Give the intent brief: the objective, the audience, and the angle of the report. " +
+            "The brief carries intent only. Do not name a path, a dataset, or a format in it, " +
+            "because the session reads those from the workspace. " +
+            "Keep the whole brief under approximately 2000 tokens. " +
+            "When the conversation holds no user turn of new work after the last report session, the tool " +
+            "starts nothing and it names that session. The ask that started that session is not new work. " +
+            "Then tell the user to continue in that chat.",
+        inputSchema: startReportSessionInput,
+        executionMode: "inline",
+        describeCall: "none",
+        execute: async (input, ctx) => {
+            const brief = {
+                objective: input.objective,
+                audience: input.audience,
+                angle: input.angle,
+                exclusions: input.exclusions,
+                openQuestions: input.openQuestions,
+            };
+            const { scope } = ctx.session;
+            if (scope.kind !== "analysis" || scope.threadId === undefined || scope.threadId.length === 0) {
+                return ok({ outcome: "refused", detail: NO_THREAD_SCOPE_DETAIL });
+            }
+            const parentThreadId = scope.threadId;
+            // The eyes gate has priority over the advice, and the advice costs two
+            // reads. The spawn holds the same gate before each read of its own,
+            // thus a blind composition reaches the `no_browser` refusal of the
+            // spawn with no read and no write. As a result the tool copies no
+            // detail line of the spawn.
+            if (eyesAvailable) {
+                const delta = await spawn.reportSessionDelta(parentThreadId);
+                if (delta.isErr()) {
+                    logger.warn("the report session delta did not read", {
+                        parentThreadId,
+                        reason: delta.error.type,
+                        ...logger.errorFields(delta.error.cause),
+                    });
+                    return ok(toOutcome(delta.error));
+                }
+                const { newestChild, userTurnsSinceAnchor } = delta.value;
+                // The rule admits one turn. A turn appends after its own loop
+                // runs, thus the ask that made the child is itself one user turn
+                // past the anchor. A rule at zero would never advise again after
+                // that turn commits. A second user turn is real work, and a new
+                // session can report on it.
+                if (input.newSessionAnyway !== true && newestChild !== null && userTurnsSinceAnchor !== null && userTurnsSinceAnchor <= 1) {
+                    return ok({ outcome: "existing-session", threadId: newestChild.threadId, title: newestChild.title });
+                }
+            }
+            const spawned = await spawn.spawnReportSession(parentThreadId, brief);
+            return ok(spawned.match((child) => ({ outcome: "started", threadId: child.threadId, title: child.title }), (fault) => {
+                const outcome = toOutcome(fault);
+                if (outcome.outcome === "failed") {
+                    logger.warn("the report session did not start", { parentThreadId, reason: fault.type, ...logger.errorFields(causeOf(fault)) });
+                }
+                return outcome;
+            }));
+        },
+    });
+}

package/dist/workflows/sandbox-step.d.ts

@@ -29,7 +29,6 @@
 import type { TokenUsageRollup } from "@inflexa-ai/harness/contracts/usage.js";
 import type { Pool } from "pg";
 import type { Logger } from "../lib/logger.js";
-import type { ResolveBilling } from "../billing/resolver.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { CitationResolver } from "../citations/types.js";
 import type { AgentDefinition, LoopMessage } from "../loop/types.js";
@@ -233,9 +232,13 @@ export interface SandboxStepDeps {
     /** Write-side embedder for the post-step vector index. */
     readonly embedding: EmbeddingProvider;
     readonly sandboxClient: SandboxClient;
-    /** Resolves the billing context stamped as the sandbox pod's OpenCost
-     *  labels. Absent in upstream-less (dev/OSS) wiring — pods spawn unlabeled. */
-    readonly resolveBilling?: ResolveBilling;
+    /**
+     * Host-supplied labels for this step's sandbox pod, resolved under the
+     * step's session. The map is opaque to the harness: it stamps each entry
+     * and interprets none of it. Absent in a wiring that attributes nothing —
+     * the pod then carries the harness's own labels only.
+     */
+    readonly resolvePodLabels?: (session: RunSession) => Promise<Record<string, string>>;
     /**
      * External artifact registration + sync seam. The harness's post-step pipeline
      * registers each step's outputs through it (filesystem index in the

package/dist/workflows/sandbox-step.js

@@ -46,8 +46,6 @@ import { createBlockerHolder } from "../tools/sandbox/report-blocker.js";
  * declare it explicitly.
  */
 export const DEFAULT_STEP_TIMEOUT_SECONDS = 3600;
-/** Resolved-header key carrying the billing-context id (see `ResolveBilling`). */
-const BILLING_CONTEXT_HEADER = "X-Inflexa-Billing-Context";
 /**
  * DBOS message topic the child uses to notify the parent that it is
  * about to self-cancel because of a 402 budget-exceeded error. The
@@ -153,7 +151,7 @@ export async function runSandboxStepBody(input, deps) {
     const identity = await DBOS.runStep(() => Promise.resolve(mintSandboxIdentity(input.runId)), { name: "sandbox.mint" });
     // (2b) sandbox.create — spawn (or adopt) the machine under the minted
     // identity. The handle (secret included) is cached so recovery picks the
-    // same machine back up without re-provisioning. Billing resolution lives
+    // same machine back up without re-provisioning. Pod-label resolution lives
     // INSIDE this step (not as its own step) so the child's step sequence is
     // unchanged — in-flight workflows resumed across a deploy replay cleanly.
     const sandboxMeta = {
@@ -166,20 +164,20 @@ export async function runSandboxStepBody(input, deps) {
         resources: input.resources,
     };
     const sandbox = await DBOS.runStep(async () => {
-        let billing;
-        if (deps.resolveBilling) {
+        let podLabels;
+        if (deps.resolvePodLabels) {
             try {
-                const bcId = (await deps.resolveBilling(session))[BILLING_CONTEXT_HEADER];
-                if (bcId)
-                    billing = { billingContextId: bcId, userId: input.runSession.identity.user };
+                podLabels = await deps.resolvePodLabels(session);
             }
             catch (err) {
-                logger.error("[billing] step billing resolution failed", { analysisId: input.analysisId, ...logger.errorFields(err) });
+                logger.warn("pod-label resolution failed", { analysisId: input.analysisId, ...logger.errorFields(err) });
             }
-            if (!billing)
-                logger.error("[billing] sandbox spawned without billing labels", { analysisId: input.analysisId });
+            // A wired resolver that yields nothing is the one loud case: the
+            // host asked for attribution and the pod spawns without it.
+            if (!podLabels || Object.keys(podLabels).length === 0)
+                logger.warn("sandbox spawned with no pod labels", { analysisId: input.analysisId });
         }
-        return deps.sandboxClient.createSandbox({ ...sandboxMeta, billing }, identity);
+        return deps.sandboxClient.createSandbox({ ...sandboxMeta, podLabels }, identity);
     }, { name: "sandbox.create" });
     // Recovery path: re-check `isAlive` on the persisted ref before continuing.
     // A classified-dead sandbox triggers a fresh `createSandbox` (task 4.6).

package/dist/workspace/paths.d.ts

@@ -122,6 +122,34 @@ export declare function stepWritePrefix(args: {
     readonly runId: string;
     readonly stepId: string;
 }): string;
+/**
+ * Split a declared sandbox write tail into its segments, and refuse a tail that is
+ * not one workspace-relative path.
+ *
+ * A tail names the one writable mount of a sandbox in place of the step directory.
+ * It reaches the mount builders from a caller, thus it takes the same discipline as
+ * a `stepId`: each segment passes {@link assertSafeId}, which refuses a separator,
+ * a NUL, a shell-hostile char, and a pure-dot segment. An empty tail names the
+ * workspace root itself, and an absolute tail names a host location. Both are
+ * refused, because a write mount must be a directory inside the tree.
+ *
+ * The segments come back so a host-path builder joins the validated parts, and it
+ * never re-splits the raw text.
+ */
+export declare function assertSafeTail(tail: string, label?: string): string[];
+/**
+ * Derive the host path of a declared write tail under a workspace root.
+ *
+ * The counterpart of {@link stepWritePrefix} for a sandbox that declares its own
+ * write tail. The tail passes the same validation before it becomes a host
+ * directory path, thus a crafted segment cannot widen or escape the mount. This is
+ * the one builder of that path: the host makes the directory with it, and the
+ * Docker bind source comes from it.
+ */
+export declare function tailWritePrefix(args: {
+    readonly workspaceRoot: string;
+    readonly tail: string;
+}): string;
 /**
  * Map a host-side absolute path within an analysis's workspace tree to its
  * in-sandbox absolute path. The tree is bind-mounted at `/{resourceId}`, so
@@ -152,6 +180,28 @@ export declare function previewDir(previewId: string): string;
  * Expects names like "v1", "v2", etc. Returns 0 if no versions found.
  */
 export declare function latestPreviewVersion(dirNames: string[]): number;
+/**
+ * Parent of every report session, workspace-root-relative. Callers that
+ * enumerate the sessions join this. Callers that address one join
+ * {@link reportSessionDir}. Both spell the segment through this constant, thus
+ * the tree has one owner.
+ */
+export declare const REPORT_SESSIONS_ROOT = "report-sessions";
+/**
+ * Directory of one report session, workspace-root-relative. The page of the
+ * session and its staged assets live under this one directory. Thus a host that
+ * reclaims the files of a purged session names each directory through this
+ * helper. The host restates no layout of the harness.
+ */
+export declare function reportSessionDir(threadId: string): string;
+/**
+ * Directory of the derived tables of one report session, workspace-root-relative.
+ *
+ * The derivation writes its output here, and the record prunes an output that the recorded document does
+ * not name. Both spell the segment through this helper, thus the write mount and the prune scope cannot
+ * disagree.
+ */
+export declare function reportSessionDerivedDir(threadId: string): string;
 /**
  * True when `value` is a safe single path segment: the `SAFE_ID` charset (word
  * chars, `.`, `-` — no slash, NUL, or shell-hostile char) AND not a pure-dot

package/dist/workspace/paths.js

@@ -96,6 +96,42 @@ export function stepWritePrefix(args) {
     assertSafeId(args.stepId, "stepId");
     return resolvePath(args.workspaceRoot, "runs", args.runId, args.stepId);
 }
+/**
+ * Split a declared sandbox write tail into its segments, and refuse a tail that is
+ * not one workspace-relative path.
+ *
+ * A tail names the one writable mount of a sandbox in place of the step directory.
+ * It reaches the mount builders from a caller, thus it takes the same discipline as
+ * a `stepId`: each segment passes {@link assertSafeId}, which refuses a separator,
+ * a NUL, a shell-hostile char, and a pure-dot segment. An empty tail names the
+ * workspace root itself, and an absolute tail names a host location. Both are
+ * refused, because a write mount must be a directory inside the tree.
+ *
+ * The segments come back so a host-path builder joins the validated parts, and it
+ * never re-splits the raw text.
+ */
+export function assertSafeTail(tail, label = "writableTail") {
+    if (tail.length === 0 || tail.startsWith("/")) {
+        throw new Error(`Invalid ${label}: ${tail}`);
+    }
+    const segments = tail.split("/");
+    for (const segment of segments) {
+        assertSafeId(segment, label);
+    }
+    return segments;
+}
+/**
+ * Derive the host path of a declared write tail under a workspace root.
+ *
+ * The counterpart of {@link stepWritePrefix} for a sandbox that declares its own
+ * write tail. The tail passes the same validation before it becomes a host
+ * directory path, thus a crafted segment cannot widen or escape the mount. This is
+ * the one builder of that path: the host makes the directory with it, and the
+ * Docker bind source comes from it.
+ */
+export function tailWritePrefix(args) {
+    return resolvePath(args.workspaceRoot, ...assertSafeTail(args.tail));
+}
 /**
  * Map a host-side absolute path within an analysis's workspace tree to its
  * in-sandbox absolute path. The tree is bind-mounted at `/{resourceId}`, so
@@ -152,6 +188,33 @@ export function latestPreviewVersion(dirNames) {
     }
     return max;
 }
+/**
+ * Parent of every report session, workspace-root-relative. Callers that
+ * enumerate the sessions join this. Callers that address one join
+ * {@link reportSessionDir}. Both spell the segment through this constant, thus
+ * the tree has one owner.
+ */
+export const REPORT_SESSIONS_ROOT = "report-sessions";
+/**
+ * Directory of one report session, workspace-root-relative. The page of the
+ * session and its staged assets live under this one directory. Thus a host that
+ * reclaims the files of a purged session names each directory through this
+ * helper. The host restates no layout of the harness.
+ */
+export function reportSessionDir(threadId) {
+    assertSafeId(threadId, "threadId");
+    return `${REPORT_SESSIONS_ROOT}/${threadId}`;
+}
+/**
+ * Directory of the derived tables of one report session, workspace-root-relative.
+ *
+ * The derivation writes its output here, and the record prunes an output that the recorded document does
+ * not name. Both spell the segment through this helper, thus the write mount and the prune scope cannot
+ * disagree.
+ */
+export function reportSessionDerivedDir(threadId) {
+    return `${reportSessionDir(threadId)}/derived`;
+}
 /**
  * For an analysis-rooted input (`/{analysisId}/...`), strip the leading
  * `/{analysisId}/` segment so it can be resolved relative to the analysis

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.19.2",
+    "version": "0.21.0",
     "description": "Host-agnostic bioinformatics agent harness \u2014 hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -64,6 +64,7 @@
         "@opentelemetry/sdk-trace-base": "^2.9.0",
         "@opentelemetry/sdk-trace-node": "^2.9.0",
         "@opentelemetry/semantic-conventions": "^1.43.0",
+        "ag-grid-community": "36.1.0",
         "ai": "^7.0.61",
         "cheerio": "^1.2.0",
         "dockerode": "^4.0.12",