@inflexa-ai/harness 0.1.1

package/dist/app/chat-turn.js

@@ -0,0 +1,64 @@
+/**
+ * Chat-turn preparation — the host-agnostic assembly half of one chat turn.
+ *
+ * This is the PREPARATION half of a conversation turn, lifted out of the HTTP
+ * route so callers other than the route (e.g. a CLI) can reuse it. It owns,
+ * in order: thread-ownership resolution, best-effort title seeding, analysis
+ * status load, and message assembly. It deliberately owns NONE of the
+ * transport orchestration (streaming/SSE/queue/status codes) — that stays in
+ * the caller. A turn is `prepareChatTurn → runAgent(own emit) → appendTurn`.
+ *
+ * Returns a typed result: `not_found` when the `threadId` is owned by a
+ * different analysis (indistinguishable from absent), otherwise `ok` with the
+ * assembled `messages` and the standalone `userMessage` the caller persists.
+ */
+import { unwrapOrThrow } from "../lib/result.js";
+import { deriveThreadTitle } from "../memory/derive-thread-title.js";
+import { createThreadHistory } from "../memory/thread-history.js";
+import { createThreadStore } from "../memory/thread-store.js";
+import { createWorkingMemory } from "../memory/working-memory.js";
+import { loadAnalysisStatus } from "../state/index.js";
+import { assembleMessages } from "./message-assembly.js";
+/**
+ * Prepare one chat turn: resolve thread ownership, seed the title, load
+ * analysis status, and assemble the message array. Input sanitization stays
+ * inside {@link assembleMessages} (applied once to the new user input only).
+ */
+export async function prepareChatTurn(deps, params) {
+    const { pool } = deps;
+    const { analysisId, threadId, userInput } = params;
+    // Ownership check before any read/write of the thread — a `threadId`
+    // owned by a different analysis is indistinguishable from a missing one.
+    const store = createThreadStore(pool);
+    const existing = unwrapOrThrow(await store.getThread(threadId));
+    if (existing && existing.analysisId !== analysisId) {
+        return { kind: "not_found" };
+    }
+    // Seed the thread title from the first user message. Best-effort.
+    try {
+        if (!existing) {
+            unwrapOrThrow(await store.createThread({
+                threadId,
+                analysisId,
+                title: deriveThreadTitle(userInput),
+            }));
+        }
+        else if (!existing.title || existing.title.length === 0) {
+            unwrapOrThrow(await store.updateTitle(threadId, deriveThreadTitle(userInput)));
+        }
+    }
+    catch (err) {
+        console.warn("[harness.chat] title-seed failed (non-fatal):", err instanceof Error ? err.message : err);
+    }
+    const analysisState = await loadAnalysisStatus(pool, analysisId).unwrapOr(null);
+    const history = createThreadHistory(pool);
+    const { messages, userMessage } = await assembleMessages({
+        threadId,
+        analysisId,
+        userInput,
+        analysisContext: analysisState?.context ?? null,
+        history,
+        workingMemory: createWorkingMemory(pool),
+    });
+    return { kind: "ok", messages, userMessage };
+}

package/dist/app/data-profile-policy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Data-profile policy — the pure decision an embedder applies when it reads a
+ * data-profile status (see CONTEXT.md "Application service layer"). It decides
+ * whether to (re)trigger profiling; the embedder executes the staging + trigger
+ * — staging stays embedder-side per the data-profile-init spec, and the atomic running→expired
+ * flip stays an SQL guard (`expireStaleDataProfile`), not part of this decision.
+ */
+export type DataProfileLifecycleStatus = "pending" | "running" | "completed" | "failed";
+/**
+ * A completed profile is stale when the analysis's seed input set no longer
+ * matches the set the profile actually covered — a file was added or swapped
+ * since profiling. An empty seed set is never stale (nothing to compare).
+ */
+export declare function isDataProfileStale(seedInputFileIds: readonly string[], profiledInputFileIds: readonly string[]): boolean;
+export type DataProfileAction = {
+    readonly kind: "none";
+} | {
+    readonly kind: "trigger";
+} | {
+    readonly kind: "retrigger";
+};
+export interface DataProfileDecisionInput {
+    readonly status: DataProfileLifecycleStatus;
+    readonly seedInputFileIds: readonly string[];
+    readonly profiledInputFileIds: readonly string[];
+}
+/**
+ * Decide the next profiling action from a (post-expire) status:
+ *   - `pending`            → `trigger`   (first profile)
+ *   - `completed` && stale → `retrigger` (inputs changed since profiling)
+ *   - anything else        → `none`
+ *
+ * `running` is left to finish (or to the SQL expiry guard); `failed` is retried
+ * explicitly via the retry route, never implicitly on read.
+ */
+export declare function decideDataProfileAction(input: DataProfileDecisionInput): DataProfileAction;

package/dist/app/data-profile-policy.js

@@ -0,0 +1,37 @@
+/**
+ * Data-profile policy — the pure decision an embedder applies when it reads a
+ * data-profile status (see CONTEXT.md "Application service layer"). It decides
+ * whether to (re)trigger profiling; the embedder executes the staging + trigger
+ * — staging stays embedder-side per the data-profile-init spec, and the atomic running→expired
+ * flip stays an SQL guard (`expireStaleDataProfile`), not part of this decision.
+ */
+/**
+ * A completed profile is stale when the analysis's seed input set no longer
+ * matches the set the profile actually covered — a file was added or swapped
+ * since profiling. An empty seed set is never stale (nothing to compare).
+ */
+export function isDataProfileStale(seedInputFileIds, profiledInputFileIds) {
+    if (seedInputFileIds.length === 0)
+        return false;
+    if (seedInputFileIds.length !== profiledInputFileIds.length)
+        return true;
+    const profiled = new Set(profiledInputFileIds);
+    return seedInputFileIds.some((id) => !profiled.has(id));
+}
+/**
+ * Decide the next profiling action from a (post-expire) status:
+ *   - `pending`            → `trigger`   (first profile)
+ *   - `completed` && stale → `retrigger` (inputs changed since profiling)
+ *   - anything else        → `none`
+ *
+ * `running` is left to finish (or to the SQL expiry guard); `failed` is retried
+ * explicitly via the retry route, never implicitly on read.
+ */
+export function decideDataProfileAction(input) {
+    if (input.status === "pending")
+        return { kind: "trigger" };
+    if (input.status === "completed" && isDataProfileStale(input.seedInputFileIds, input.profiledInputFileIds)) {
+        return { kind: "retrigger" };
+    }
+    return { kind: "none" };
+}

package/dist/app/message-assembly.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Chat-turn message assembly.
+ *
+ * Builds the `messages` array `runAgent` receives for one conversation turn:
+ *
+ *   [ ...loadRecent(threadId, budget)            ← stable, cacheable prefix
+ *     {user: cortex_analysis_state.context},     ← tail
+ *     {user: render(workingMemory)},             ← tail
+ *     {user: normalizeUnicode(redactSecrets(input))} ]  ← tail
+ *
+ * `system + tools + history` is the cacheable prefix — it only extends
+ * turn-to-turn. Working memory and analysis context go in the **tail** as
+ * `user` messages: working memory changes every turn, so a system-message
+ * placement would bust the Anthropic cache prefix.
+ *
+ * Sanitization (`redactSecrets`, `normalizeUnicode`) is applied **once**, to
+ * the new user input only — never to history, assistant messages, tool
+ * results, the analysis context, or the rendered working memory.
+ *
+ * The returned `userMessage` is the sanitized user input on its own — the
+ * route persists `[userMessage, ...loop output]` via `appendTurn`, so the
+ * tail injections (ephemeral, re-derived each turn) are never written to the
+ * thread store.
+ */
+import type { ModelMessage } from "ai";
+import type { LoopMessage } from "../loop/types.js";
+import type { ThreadHistory } from "../memory/thread-history.js";
+import type { WorkingMemoryStore } from "../memory/working-memory.js";
+/**
+ * Token budget for the `loadRecent` history window. Sized to leave headroom
+ * under the model context window for the system prompt, tool definitions,
+ * the three tail messages, and the output budget.
+ */
+export declare const DEFAULT_HISTORY_TOKEN_BUDGET = 120000;
+export interface AssembleMessagesArgs {
+    /** The conversation thread — a UI-generated UUID, never the analysisId. */
+    readonly threadId: string;
+    /** The analysis scope — keys working memory and (separately) the context. */
+    readonly analysisId: string;
+    /** The raw, untrusted user input for this turn. */
+    readonly userInput: string;
+    /** `cortex_analysis_state.context`, already read by the route. `null` when absent. */
+    readonly analysisContext: string | null;
+    /** The conversation message store — supplies the history window. */
+    readonly history: ThreadHistory;
+    /** The working-memory store — rendered into the tail. */
+    readonly workingMemory: WorkingMemoryStore;
+    /** History-window token budget. Defaults to {@link DEFAULT_HISTORY_TOKEN_BUDGET}. */
+    readonly tokenBudget?: number;
+}
+export interface AssembledMessages {
+    /** The full message array for `runAgent`. */
+    readonly messages: LoopMessage[];
+    /**
+     * The sanitized user input as its own message — the genuine turn start.
+     * The route persists this plus the loop's output; the tail injections are
+     * not persisted.
+     */
+    readonly userMessage: ModelMessage;
+}
+/**
+ * Assemble the message array for one chat turn. Async — it reads the history
+ * window and renders working memory.
+ */
+export declare function assembleMessages(args: AssembleMessagesArgs): Promise<AssembledMessages>;

package/dist/app/message-assembly.js

@@ -0,0 +1,61 @@
+/**
+ * Chat-turn message assembly.
+ *
+ * Builds the `messages` array `runAgent` receives for one conversation turn:
+ *
+ *   [ ...loadRecent(threadId, budget)            ← stable, cacheable prefix
+ *     {user: cortex_analysis_state.context},     ← tail
+ *     {user: render(workingMemory)},             ← tail
+ *     {user: normalizeUnicode(redactSecrets(input))} ]  ← tail
+ *
+ * `system + tools + history` is the cacheable prefix — it only extends
+ * turn-to-turn. Working memory and analysis context go in the **tail** as
+ * `user` messages: working memory changes every turn, so a system-message
+ * placement would bust the Anthropic cache prefix.
+ *
+ * Sanitization (`redactSecrets`, `normalizeUnicode`) is applied **once**, to
+ * the new user input only — never to history, assistant messages, tool
+ * results, the analysis context, or the rendered working memory.
+ *
+ * The returned `userMessage` is the sanitized user input on its own — the
+ * route persists `[userMessage, ...loop output]` via `appendTurn`, so the
+ * tail injections (ephemeral, re-derived each turn) are never written to the
+ * thread store.
+ */
+import { unwrapOrThrow } from "../lib/result.js";
+import { normalizeUnicode, redactSecrets } from "../input-sanitization.js";
+/**
+ * Token budget for the `loadRecent` history window. Sized to leave headroom
+ * under the model context window for the system prompt, tool definitions,
+ * the three tail messages, and the output budget.
+ */
+export const DEFAULT_HISTORY_TOKEN_BUDGET = 120_000;
+/**
+ * Assemble the message array for one chat turn. Async — it reads the history
+ * window and renders working memory.
+ */
+export async function assembleMessages(args) {
+    const budget = args.tokenBudget ?? DEFAULT_HISTORY_TOKEN_BUDGET;
+    const history = unwrapOrThrow(await args.history.loadRecent(args.threadId, budget));
+    // Sanitization — applied once, here, to the new user input only.
+    const userMessage = {
+        role: "user",
+        content: normalizeUnicode(redactSecrets(args.userInput)),
+    };
+    const tail = [];
+    // Analysis context — platform-supplied, trusted. Injected only when present.
+    if (args.analysisContext && args.analysisContext.trim().length > 0) {
+        tail.push({
+            role: "user",
+            content: `[Analysis Context]\n${args.analysisContext}`,
+        });
+    }
+    // Working memory — agent-authored, trusted. Always injected (its rendered
+    // form names the sections even when empty).
+    tail.push({
+        role: "user",
+        content: unwrapOrThrow(await args.workingMemory.render(args.analysisId)),
+    });
+    tail.push(userMessage);
+    return { messages: [...history, ...tail], userMessage };
+}

package/dist/app/synthesize-run.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Run-level synthesis — the host-agnostic ability lifted out of the managed
+ * workflow-dep closure so every embedder reuses it (see CONTEXT.md
+ * "Application service layer"). Loads the completed run's step summaries,
+ * drives the literature-grounded synthesizer, indexes + persists the result,
+ * and reports progress phases — returning the quick-display findings for the
+ * run-completed card.
+ *
+ * Owns the ability end-to-end; owns no transport. The injected `embedding`
+ * provider carries the host's own billing choice (a no-op locally); `emit` is
+ * the loop/chat-part sink the caller binds to its stream; `onProgress`
+ * is the domain progress callback the caller serializes to the wire. A genuine
+ * synthesis failure re-throws (D10) so the caller fails the run loudly; the
+ * honest non-fatal outcomes (no summaries, blocker) return empty findings after
+ * a `skipped` phase.
+ */
+import type { Pool } from "pg";
+import type { SynthesisPhase } from "@inflexa-ai/harness/contracts/chat-parts.js";
+import type { RunSession } from "../auth/types.js";
+import type { EmitFn } from "../loop/types.js";
+import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
+import type { BioToolKeys } from "../tools/bio/keys.js";
+import type { RunFinding } from "../workflows/execute-analysis.js";
+import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
+export interface SynthesizeRunDeps {
+    readonly pool: Pool;
+    readonly provider: ChatProvider;
+    /** Write-side embedder — its `dimensions` sizes the per-analysis index. */
+    readonly embedding: EmbeddingProvider;
+    /** Embedder-supplied workspace-root resolution seam (see workspace/paths.ts). */
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    /** Model id for the synthesizer agent loop. */
+    readonly synthesisModel: string;
+    /** API keys for the bio/chem tools the embedded literature reviewer uses. */
+    readonly bioKeys: BioToolKeys;
+}
+/** Optional fields for a progress update, mirroring the wire part. */
+export interface SynthesisProgressExtra {
+    readonly delegationCount?: number;
+    readonly validationAttempts?: number;
+    readonly reason?: string;
+    readonly error?: string;
+}
+export interface SynthesizeRunParams {
+    readonly analysisId: string;
+    readonly runId: string;
+    readonly completedSteps: readonly string[];
+    readonly session: RunSession;
+    /** Loop-event + run-synthesis chat-part sink (forwarded to the synthesizer loop). */
+    readonly emit: EmitFn;
+    /** Domain progress callback — the phases the run-completed UI renders. */
+    readonly onProgress: (phase: SynthesisPhase, activity: string, extra?: SynthesisProgressExtra) => void | Promise<void>;
+}
+export interface SynthesizeRunResult {
+    readonly findings: readonly RunFinding[];
+}
+export declare function synthesizeRun(deps: SynthesizeRunDeps, params: SynthesizeRunParams): Promise<SynthesizeRunResult>;

package/dist/app/synthesize-run.js

@@ -0,0 +1,103 @@
+/**
+ * Run-level synthesis — the host-agnostic ability lifted out of the managed
+ * workflow-dep closure so every embedder reuses it (see CONTEXT.md
+ * "Application service layer"). Loads the completed run's step summaries,
+ * drives the literature-grounded synthesizer, indexes + persists the result,
+ * and reports progress phases — returning the quick-display findings for the
+ * run-completed card.
+ *
+ * Owns the ability end-to-end; owns no transport. The injected `embedding`
+ * provider carries the host's own billing choice (a no-op locally); `emit` is
+ * the loop/chat-part sink the caller binds to its stream; `onProgress`
+ * is the domain progress callback the caller serializes to the wire. A genuine
+ * synthesis failure re-throws (D10) so the caller fails the run loudly; the
+ * honest non-fatal outcomes (no summaries, blocker) return empty findings after
+ * a `skipped` phase.
+ */
+import { forSubAgent } from "../auth/types.js";
+import { buildRunSynthesisPart, formatSynthesisEmbeddingText, generateRunSynthesis, loadStepSummariesFromDisk, persistSynthesis, } from "../execution/run-synthesis.js";
+import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.js";
+import { createVectorStore } from "../state/vector-store.js";
+import { loadPlan, queryRun } from "../state/index.js";
+import { unwrapOrThrow } from "../lib/result.js";
+export async function synthesizeRun(deps, params) {
+    const { pool, provider, embedding, resolveWorkspaceRoot, synthesisModel, bioKeys } = deps;
+    const { analysisId, runId, completedSteps, session, emit, onProgress } = params;
+    await onProgress("starting", "Beginning literature-grounded synthesis");
+    try {
+        const workspaceRoot = resolveWorkspaceRoot(analysisId);
+        const summaries = await loadStepSummariesFromDisk({
+            workspaceRoot,
+            runId,
+            completedSteps,
+        });
+        if (summaries.length === 0) {
+            await onProgress("skipped", "No step summaries available for synthesis", {
+                reason: "no-summaries",
+            });
+            return { findings: [] };
+        }
+        const planNarrative = await loadPlanNarrative(pool, runId, analysisId);
+        const synthesizerSession = forSubAgent(session, "run-synthesizer");
+        const result = await generateRunSynthesis({
+            provider,
+            session: synthesizerSession,
+            model: synthesisModel,
+            bioKeys,
+            summaries,
+            planNarrative,
+            runId,
+            emit,
+        });
+        if (result.kind === "skipped") {
+            await onProgress("skipped", "Synthesis skipped — run did not produce synthesizable content", { reason: result.reason });
+            return { findings: [] };
+        }
+        const synthesis = result.synthesis;
+        await onProgress("indexing", "Indexing synthesis for search");
+        try {
+            await ensureSearchIndex(pool, analysisId, embedding.dimensions);
+            const vectorStore = createVectorStore(pool);
+            const indexName = searchIndexName(analysisId);
+            const synthesisText = formatSynthesisEmbeddingText(synthesis);
+            const [vector] = unwrapOrThrow(await embedding.embed([synthesisText], synthesizerSession));
+            if (!vector)
+                throw new Error("synthesize-run: empty embedding response");
+            unwrapOrThrow(await vectorStore.upsert({
+                indexName,
+                vectors: [vector],
+                metadata: [{ text: synthesisText, type: "synthesis", runId }],
+                ids: [`/${analysisId}/runs/${runId}/synthesis.json`],
+            }));
+        }
+        catch (indexErr) {
+            console.warn(`[synthesize-run] vector indexing failed for run ${runId}:`, indexErr instanceof Error ? indexErr.message : indexErr);
+        }
+        await onProgress("persisting", "Persisting synthesis");
+        await persistSynthesis({ workspaceRoot, runId, synthesis });
+        await emit(buildRunSynthesisPart(runId, synthesis));
+        await onProgress("complete", "Literature-grounded synthesis ready");
+        return {
+            findings: synthesis.findings.map((f) => ({
+                title: f.title,
+                confidence: f.confidence,
+            })),
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        await onProgress("failed", "Synthesis could not be completed — step summaries are still available", { error: msg });
+        // A genuine synthesis failure must fail the run loudly (D10): re-throw so
+        // the synthesis step errors and the parent workflow goes to ERROR. The
+        // honest non-fatal outcomes (no-summaries / blocker) early-return above.
+        throw err;
+    }
+}
+async function loadPlanNarrative(pool, runId, analysisId) {
+    const run = unwrapOrThrow(await queryRun(pool, runId));
+    const planId = run?.planId ?? null;
+    if (!planId)
+        return "";
+    const plan = unwrapOrThrow(await loadPlan(pool, planId, { analysisId }));
+    return plan?.analytical_narrative ?? "";
+}

package/dist/auth/local-auth-context.d.ts

@@ -0,0 +1,19 @@
+/**
+ * OSS realization of the opaque `AuthContext`.
+ *
+ * The harness carries `AuthContext` through every session but never inspects it (see
+ * `auth/types.ts`). The managed build backs it with a concrete
+ * credential + org (`makeManagedAuth` in `auth-context.ts`); the OSS build
+ * supplies this trivial value instead — it carries no credential and no org,
+ * and no adapter ever downcasts it. Local code forwards `auth` untouched and
+ * MUST NOT call `getAuth` (which would downcast this empty value to a managed
+ * credential that isn't there).
+ */
+import type { AuthContext } from "./types.js";
+/**
+ * Build the trivial opaque `auth` value an OSS session constructor stores.
+ * Returned as `AuthContext` so callers stay credential-blind. The cast bridges
+ * the empty literal to the phantom-branded interface; the brand is an optional
+ * `never`, so no real field is fabricated.
+ */
+export declare function makeLocalAuth(): AuthContext;

package/dist/auth/local-auth-context.js

@@ -0,0 +1,20 @@
+/**
+ * OSS realization of the opaque `AuthContext`.
+ *
+ * The harness carries `AuthContext` through every session but never inspects it (see
+ * `auth/types.ts`). The managed build backs it with a concrete
+ * credential + org (`makeManagedAuth` in `auth-context.ts`); the OSS build
+ * supplies this trivial value instead — it carries no credential and no org,
+ * and no adapter ever downcasts it. Local code forwards `auth` untouched and
+ * MUST NOT call `getAuth` (which would downcast this empty value to a managed
+ * credential that isn't there).
+ */
+/**
+ * Build the trivial opaque `auth` value an OSS session constructor stores.
+ * Returned as `AuthContext` so callers stay credential-blind. The cast bridges
+ * the empty literal to the phantom-branded interface; the brand is an optional
+ * `never`, so no real field is fabricated.
+ */
+export function makeLocalAuth() {
+    return {};
+}

package/dist/auth/local-run-authorizer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * LocalRunAuthorizer — the OSS realization of the `RunAuthorizer` seam.
+ *
+ * Issues a durable `RunSession` straight from the async-edge input: no remote
+ * authorization, no credential read. It owns nothing revocable, so `revoke` is
+ * a no-op. The opaque caller `auth` is forwarded untouched — local code never
+ * inspects it (no `getAuth`).
+ */
+import type { RunAuthorizer } from "../execution/run-authorizer.js";
+export declare function createLocalRunAuthorizer(): RunAuthorizer;

package/dist/auth/local-run-authorizer.js

@@ -0,0 +1,23 @@
+/**
+ * LocalRunAuthorizer — the OSS realization of the `RunAuthorizer` seam.
+ *
+ * Issues a durable `RunSession` straight from the async-edge input: no remote
+ * authorization, no credential read. It owns nothing revocable, so `revoke` is
+ * a no-op. The opaque caller `auth` is forwarded untouched — local code never
+ * inspects it (no `getAuth`).
+ */
+export function createLocalRunAuthorizer() {
+    return {
+        async authorize({ auth, scope, provenance, frame }) {
+            const runSession = {
+                identity: { user: "local" },
+                scope,
+                provenance,
+                runFrame: frame,
+                auth,
+            };
+            return { runSession, ownsMandate: false }; // oss-core-managed-ok
+        },
+        async revoke() { },
+    };
+}

package/dist/auth/types.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Request identity — typed value objects and the two lifetime-typed bundles.
+ *
+ * Per-request identity is decomposed into small immutable value objects
+ * (`Identity`, `Scope`, `Credential`, `Provenance`, `RunFrame`) plus an opaque
+ * `auth` capability (`AuthContext`), instead of the old flat `Session`
+ * grab-bag. The `auth` capability is the sole carrier of credential/org behind
+ * a session — there is no top-level `orgId` or `credential` field. Optional
+ * concerns are whole present-or-absent sub-objects: a `RunFrame` exists or it
+ * doesn't; a `Credential` is an opaque bearer capability — never a nullable
+ * field. Its concrete shape is a managed refinement; the harness never inspects it.
+ *
+ * Two bundles compose those objects with honest lifetimes:
+ *   - `RequestSession` — the live HTTP door. No RunFrame; never JSON-serialized
+ *     into durable state.
+ *   - `RunSession` — durable, JSON-serializable. Carries a `RunFrame`; minted
+ *     only at the run-authorization seam.
+ *
+ * Neither bundle carries resolved billing headers — billing is resolved
+ * lazily at the LLM call site (see `harness/billing/resolver.ts`).
+ */
+/** Who the request is. Always complete. */
+export interface Identity {
+    readonly user: string;
+}
+/**
+ * What the request operates on — a discriminated union owning its resource
+ * coordinates (`scopeResource`) and the workload id (`scopeWorkloadId`) used
+ * for attribution. `threadId` lives on the analysis variant only.
+ */
+export type Scope = {
+    readonly kind: "analysis";
+    readonly analysisId: string;
+    readonly threadId?: string;
+} | {
+    readonly kind: "target-assessment";
+    readonly targetAssessmentId: string;
+    readonly billingContextId: string;
+};
+declare const CRED_BRAND: unique symbol;
+/**
+ * Opaque bearer credential. The harness forwards it through the loop, providers, and
+ * tools but NEVER inspects it — it has no readable fields. Only managed seam
+ * adapters downcast it to their concrete realization, at a single contained
+ * cast per reader. The optional phantom brand keeps the harness from reading any field
+ * off it while still letting a concrete managed credential satisfy it
+ * structurally.
+ */
+export interface Credential {
+    readonly [CRED_BRAND]?: never;
+}
+/**
+ * The agent call chain at the point of a call. Read-only provenance —
+ * events, logs, and OTel spans read it; control flow MUST NOT branch on it.
+ */
+export interface Provenance {
+    readonly agentId: string;
+    readonly callPath: readonly string[];
+}
+/** Present only inside a workflow run. */
+export interface RunFrame {
+    readonly runId: string;
+    readonly stepId?: string;
+}
+/** Canonical resource coordinates a `Scope` resolves to. */
+export interface ResourceCoordinates {
+    readonly resourceType: "analysis" | "billing_context";
+    readonly resourceId: string;
+}
+/**
+ * Derive the `{ resourceType, resourceId }` a scope resolves through.
+ * Analysis → `{ "analysis", analysisId }`; target-assessment →
+ * `{ "billing_context", billingContextId }` (TA resolves billing via the
+ * billing-context discriminator until it is a first-class resource).
+ */
+export declare function scopeResource(scope: Scope): ResourceCoordinates;
+/** The value stamped into the workload tag — the workload id for this scope. */
+export declare function scopeWorkloadId(scope: Scope): string;
+declare const AUTH_BRAND: unique symbol;
+/**
+ * The opaque inward auth capability carried by every session. The harness forwards it
+ * through the loop, providers, and tools but NEVER inspects it — it has no
+ * readable fields. Only managed seam adapters downcast it to their concrete
+ * realization (`ManagedAuthContext = { credential, orgId }` in
+ * `auth-context.ts`), at a single contained cast per adapter. OSS supplies a
+ * trivial value. The optional phantom brand keeps the harness from reading any field
+ * off it while still letting a managed `{ credential, orgId }` literal satisfy
+ * it structurally.
+ */
+export interface AuthContext {
+    readonly [AUTH_BRAND]?: never;
+}
+/**
+ * The session view the agent loop, the provider seam, and tools accept —
+ * the union of what every layer below the HTTP door actually reads. The
+ * session is a conduit: `runAgent` forwards it to the provider and into each
+ * tool; tools forward it to `embed` and into nested `runAgent`s. The deepest
+ * consumer is the provider, which reads every field, so the conduit type is
+ * "all fields, generalized to what's read" — `credential` widened to the
+ * opaque `Credential` (nothing in the harness branches on the concrete shape),
+ * `runFrame` optional (only the billing assembler reads it).
+ *
+ * Both bundles satisfy this: a `RequestSession` (no RunFrame) and a
+ * `RunSession` (with RunFrame) are each structurally assignable, so the
+ * same agent loop runs under a live request and inside a durable workflow.
+ */
+export interface AgentSession {
+    readonly identity: Identity;
+    readonly scope: Scope;
+    readonly provenance: Provenance;
+    readonly runFrame?: RunFrame;
+    /**
+     * Opaque inward auth capability — the ONLY auth the harness conduit carries.
+     * The harness forwards it but never inspects it; managed adapters downcast it via
+     * `getAuth`. The sole source of credential/org behind a session.
+     */
+    readonly auth: AuthContext;
+}
+/**
+ * The live HTTP door. No `RunFrame` — `runId`/`stepId` are unrepresentable
+ * until async work is authorized. SHALL NOT be JSON-serialized into durable
+ * state.
+ */
+export interface RequestSession {
+    readonly identity: Identity;
+    readonly scope: Scope;
+    readonly provenance: Provenance;
+    readonly auth: AuthContext;
+}
+/**
+ * The durable, JSON-serializable bundle. Carries a `RunFrame`. Constructed
+ * solely at the run-authorization seam.
+ */
+export interface RunSession {
+    readonly identity: Identity;
+    readonly scope: Scope;
+    readonly provenance: Provenance;
+    readonly runFrame: RunFrame;
+    readonly auth: AuthContext;
+}
+/**
+ * The minimal session view the billing-header assembler reads. Both bundles
+ * satisfy it; `runFrame` is present only on a `RunSession`, so a
+ * `RequestSession` emits no run/step tags.
+ */
+export interface BillingSessionView {
+    readonly identity: Identity;
+    readonly scope: Scope;
+    readonly provenance: Provenance;
+    readonly runFrame?: RunFrame;
+}
+/**
+ * Derive a child session for a sub-agent call — provenance only. Sets the
+ * child `agentId` and appends it to `callPath`, leaving identity, scope, and
+ * auth untouched. Works on either bundle (the input type is preserved).
+ */
+export declare function forSubAgent<S extends {
+    readonly provenance: Provenance;
+}>(session: S, agentId: string): S;
+/**
+ * Derive a child `RunSession` for a sandbox step — pure value derivation.
+ * Sets `runFrame.stepId`; identity, scope, auth, and provenance are
+ * unchanged. Used by parents when computing child workflow input.
+ */
+export declare function forStep(parent: RunSession, stepId: string): RunSession;
+export {};