@inflexa-ai/harness 0.1.1

package/dist/provenance/collector.js

@@ -0,0 +1,296 @@
+/**
+ * Step-level provenance collector — tracks inputs consumed and outputs
+ * produced within a single workflow step.
+ *
+ * Integrates with:
+ *   - K8sSandbox executeCommand provenance (script reads + writes via inotify)
+ *   - Data-mount filesystem write tracking (agent file-tool outputs)
+ *
+ * Input attribution comes exclusively from sandbox exec inotify (the
+ * authoritative record of what computation actually consumed). Agent
+ * tool reads are not tracked here — they're exploratory and would
+ * pollute the lineage graph.
+ */
+// ── Script path inference ───────────────────────────────────────────
+/** Known interpreter prefixes for script path extraction. */
+const SCRIPT_PATTERNS = [/^python3?\s+(.+)$/, /^Rscript\s+(.+)$/, /^bash\s+(.+)$/, /^sh\s+(.+)$/];
+/**
+ * Attempt to extract the script path from a command string.
+ * Returns the first argument that looks like a file path for known interpreters.
+ */
+function inferScriptPath(command, args) {
+    const fullCommand = args?.length ? `${command} ${args.join(" ")}` : command;
+    for (const pattern of SCRIPT_PATTERNS) {
+        const match = fullCommand.match(pattern);
+        if (match?.[1]) {
+            // Take the first token (the script path), ignoring further args
+            return match[1].split(/\s+/)[0];
+        }
+    }
+    return null;
+}
+/**
+ * Build classification context for a file read using known step metadata.
+ *
+ * Uses prefix matching against structured metadata — no path segment
+ * extraction. The caller knows its own stepId/runId and its upstream
+ * dependencies (dependsOn).
+ *
+ * For prior-run reads (paths under runs/ that don't match own run or
+ * any dependsOn entry), this falls back to path extraction — see the
+ * prior-run branch below for why.
+ */
+export function classifyReadPath(relativePath, ownStepId, ownRunId, dependsOn) {
+    if (relativePath.startsWith("data/") || relativePath.startsWith("dataprofile/")) {
+        return { source: "data" };
+    }
+    // Own artifacts: runs/{ownRunId}/{ownStepId}/...
+    const ownPrefix = `runs/${ownRunId}/${ownStepId}/`;
+    if (relativePath.startsWith(ownPrefix)) {
+        return { source: "artifacts", stepId: ownStepId, runId: ownRunId };
+    }
+    // Upstream dependencies: runs/{ownRunId}/{depStepId}/...
+    if (dependsOn) {
+        for (const depStepId of dependsOn) {
+            const upstreamPrefix = `runs/${ownRunId}/${depStepId}/`;
+            if (relativePath.startsWith(upstreamPrefix)) {
+                return { source: "upstream", stepId: depStepId, runId: ownRunId };
+            }
+        }
+    }
+    // Same-run sibling step. dependsOn only drives topo-sort ordering, not
+    // read authorization, so a read outside dependsOn is still a valid
+    // upstream input — just extract the stepId from the path.
+    const ownRunPrefix = `runs/${ownRunId}/`;
+    if (relativePath.startsWith(ownRunPrefix)) {
+        const afterRun = relativePath.slice(ownRunPrefix.length);
+        const slashIdx = afterRun.indexOf("/");
+        const stepId = slashIdx > 0 ? afterRun.slice(0, slashIdx) : afterRun;
+        if (stepId) {
+            return { source: "upstream", stepId, runId: ownRunId };
+        }
+    }
+    // Prior-run fallback: a read under `runs/{otherRunId}/...` that is neither
+    // this step's own run nor a `dependsOn` entry carries no step metadata
+    // linking it, so the path segments are the only source for the
+    // `{source: "prior", runId, stepId}` classification. This is the one place
+    // the provenance system extracts identity from path segments.
+    if (relativePath.startsWith("runs/")) {
+        const parts = relativePath.split("/");
+        const priorRunId = parts[1];
+        const priorStepId = parts[2];
+        if (priorRunId && priorStepId) {
+            return { source: "prior", stepId: priorStepId, runId: priorRunId };
+        }
+    }
+    return { source: "data" };
+}
+export class ProvenanceCollector {
+    stepId;
+    runId;
+    dependsOn;
+    /** Prefix for converting analysis-relative write paths to step-relative. */
+    stepPrefix;
+    /**
+     * Map from input file relative path (e.g., "inputs/Lab A Storage/trail_0/data.csv")
+     * to fileId. Sourced from the data-mount filesystem's inputPathToFileId map
+     * (passed by reference, populated lazily during filesystem init).
+     */
+    inputFileIdMap;
+    /** Tracked reads from read-only mounts, keyed by `mountPath:relativePath`. */
+    inputAccesses = new Map();
+    /** File tool write records, keyed by output path (relative to /artifacts). */
+    fileToolRecords = new Map();
+    /** Command execution records, keyed by output path (relative to /artifacts). */
+    commandRecords = new Map();
+    constructor(opts) {
+        this.stepId = opts.stepId;
+        this.runId = opts.runId;
+        this.dependsOn = opts.dependsOn ?? [];
+        this.stepPrefix = `runs/${opts.runId}/${opts.stepId}/`;
+    }
+    /**
+     * Set the input file ID map (passed by reference from the data-mount filesystem).
+     * Called after construction when the data mount filesystem is available.
+     */
+    setInputFileIdMap(map) {
+        this.inputFileIdMap = map;
+    }
+    /**
+     * Track a file read from a read-only mount.
+     * Called by sandbox exec provenance frame processing.
+     *
+     * @param mountPath - The workspace mount path (e.g., "/a1/data" or "/a1" for single-mount)
+     * @param relativePath - Path relative to the mount root
+     * @param hash - SHA-256 hash of the file content, or null if file no longer exists
+     * @param context - Explicit classification context from the caller. When provided,
+     *   the collector uses it directly instead of classifying from the path.
+     */
+    trackInputAccess(mountPath, relativePath, hash, context) {
+        const key = `${mountPath}:${relativePath}`;
+        const existing = this.inputAccesses.get(key);
+        if (existing)
+            return existing;
+        // Use explicit context if provided, otherwise fall back to path classification
+        const classification = context ?? classifyReadPath(relativePath, this.stepId, this.runId, this.dependsOn);
+        const fullPath = `${mountPath}/${relativePath}`;
+        // Resolve fileId for data-source inputs via materialized file metadata map
+        let fileId;
+        if (classification.source === "data" && this.inputFileIdMap) {
+            fileId = this.inputFileIdMap.get(relativePath);
+        }
+        const ref = {
+            path: fullPath,
+            hash: hash ?? "",
+            source: classification.source,
+            stepId: classification.stepId,
+            runId: classification.runId,
+            fileId,
+        };
+        this.inputAccesses.set(key, ref);
+        return ref;
+    }
+    /**
+     * Record a file tool write (write_file, edit_file).
+     * Called after the data-mount filesystem records the artifact.
+     *
+     * File tool writes are agent-authored content — not derived from input
+     * files via execution — so no inputs are attributed.
+     */
+    recordFileToolWrite(artifact) {
+        // Normalize analysis-relative paths to step-relative (mirroring
+        // recordCommandExecution) so file-tool and command records land in one
+        // keyspace. Without this the cross-feed last-write-wins unlink dead-fires
+        // and registration's step-relative lookup never finds this record.
+        const outputPath = artifact.path.startsWith(this.stepPrefix) ? artifact.path.slice(this.stepPrefix.length) : artifact.path;
+        // Last-write-wins: unlink any command record for this path.
+        // Post-step overwrites (e.g. summary generation) replace the command output.
+        this.commandRecords.delete(outputPath);
+        const record = {
+            outputPath,
+            outputHash: artifact.hash,
+            outputSize: artifact.size,
+            producer: {
+                type: "file_tool",
+                tool: artifact.toolName ?? "unknown",
+                timestamp: artifact.timestamp,
+            },
+            inputs: [],
+            scriptPath: null,
+            stepId: this.stepId,
+            runId: this.runId,
+        };
+        this.fileToolRecords.set(outputPath, record);
+    }
+    /**
+     * Record outputs from a sandbox command execution.
+     * Called after provenance frame processing extracts observed writes.
+     *
+     * When commandReads is provided, uses those as the inputs for this
+     * command's provenance records (per-command scoping). Falls back to
+     * snapshotting the global inputAccesses accumulator when not provided.
+     */
+    recordCommandExecution(command, args, exitCode, durationMs, writes, scriptPath, commandReads) {
+        const inputs = commandReads ?? Array.from(this.inputAccesses.values());
+        const resolvedScript = scriptPath ?? inferScriptPath(command, args);
+        const timestamp = new Date().toISOString();
+        const producer = {
+            type: "command",
+            command,
+            args: args.length > 0 ? args : undefined,
+            exitCode,
+            durationMs,
+            timestamp,
+        };
+        for (const write of writes) {
+            // Normalize analysis-relative paths to step-relative so keys match
+            // the data-mount filesystem's localArtifacts and the artifact manifest.
+            const outputPath = write.path.startsWith(this.stepPrefix) ? write.path.slice(this.stepPrefix.length) : write.path;
+            const record = {
+                outputPath,
+                outputHash: write.hash,
+                outputSize: write.size,
+                producer,
+                inputs,
+                scriptPath: resolvedScript,
+                stepId: this.stepId,
+                runId: this.runId,
+            };
+            // Last-write-wins: unlink any file-tool record for this path.
+            this.fileToolRecords.delete(outputPath);
+            this.commandRecords.set(outputPath, record);
+        }
+    }
+    /**
+     * Get provenance inputs classified as `source: "data"` (input files read from /data mount).
+     */
+    getDataInputs() {
+        return Array.from(this.inputAccesses.values()).filter((ref) => ref.source === "data");
+    }
+    /**
+     * All distinct input refs observed this step, any source. The returned refs
+     * are the live objects also held by the per-command records, so repairing a
+     * `hash` here (e.g. `reconcileManifestWithDisk` filling read hashes from
+     * disk) propagates into the registration payload.
+     */
+    getTrackedInputs() {
+        return Array.from(this.inputAccesses.values());
+    }
+    /**
+     * Drop an input ref from lineage entirely — removes it from the tracked-input
+     * map and from every record's `inputs` array (identity match, since the refs
+     * are shared objects). `reconcileManifestWithDisk` calls this for a read that
+     * resolves to a directory (e.g. an `ls` / `list.files` of a mount): the
+     * inotify frame tracks the open, but a directory is not a content-attestable
+     * file artifact and must never reach registration. Mirrors the output-side
+     * non-file drop.
+     */
+    dropInput(ref) {
+        for (const [key, val] of this.inputAccesses) {
+            if (val === ref) {
+                this.inputAccesses.delete(key);
+                break;
+            }
+        }
+        const scrub = (rec) => {
+            if (rec.inputs.some((i) => i === ref)) {
+                rec.inputs = rec.inputs.filter((i) => i !== ref);
+            }
+        };
+        for (const rec of this.commandRecords.values())
+            scrub(rec);
+        for (const rec of this.fileToolRecords.values())
+            scrub(rec);
+    }
+    /**
+     * Get merged, deduplicated provenance records.
+     * Command records win over file-tool records for the same output path.
+     */
+    getRecords() {
+        const merged = new Map(this.fileToolRecords);
+        // Command records overwrite file-tool records (command overwrote the file)
+        for (const [path, record] of this.commandRecords) {
+            merged.set(path, record);
+        }
+        return Array.from(merged.values());
+    }
+    /** Remove any record (command or file-tool) for the given output path. */
+    removeRecord(path) {
+        this.commandRecords.delete(path);
+        this.fileToolRecords.delete(path);
+    }
+    /**
+     * Replace the existing record for `record.outputPath` while preserving
+     * last-write-wins ordering (command beats file-tool). If a command record
+     * exists, the replacement overwrites it; otherwise the file-tool record
+     * is overwritten. If neither exists, the replacement is stored as a
+     * file-tool record so `getRecords()` surfaces it.
+     */
+    replaceRecord(record) {
+        if (this.commandRecords.has(record.outputPath)) {
+            this.commandRecords.set(record.outputPath, record);
+            return;
+        }
+        this.fileToolRecords.set(record.outputPath, record);
+    }
+}

package/dist/provenance/exec-frame.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Feed a sandbox-server exec provenance frame into the step's
+ * `ProvenanceCollector`.
+ *
+ * Frame paths are absolute container paths under the analysis resource
+ * mount (`/{resourceId}/...`). This helper strips the mount prefix to
+ * analysis-relative (`data/...`, `runs/{runId}/{stepId}/...`,
+ * `runs/{priorRunId}/...`) so `classifyReadPath` and the collector's
+ * `stepPrefix` normalization see the shapes they expect.
+ *
+ * Degrades safely: a disabled or absent frame records the command with no
+ * inputs and no writes (its outputs fall back to leaves at registration).
+ * It never throws — provenance is best-effort and must not fail an exec.
+ */
+import type { ProvenanceFrame } from "../sandbox/types.js";
+import { type ProvenanceCollector } from "./collector.js";
+/** Strip the `/{resourceId}/` mount prefix from an absolute frame path. */
+export declare function stripMountPrefix(mountRoot: string, absPath: string): string;
+export interface FeedExecFrameArgs {
+    readonly collector: ProvenanceCollector;
+    /** Analysis resource mount root, e.g. `/{resourceId}`. */
+    readonly mountRoot: string;
+    /** The argv the harness submitted in `SubmitExecBody`. */
+    readonly command: readonly string[];
+    readonly exitCode: number | null;
+    readonly durationMs: number | null;
+    /** The frame surfaced on `ExecResult.provenance` (may be absent). */
+    readonly provenance?: ProvenanceFrame;
+}
+/**
+ * Translate one exec's frame into a collector record. Per-command input
+ * scoping: only the reads observed for THIS exec are attached to its
+ * outputs (not the step's global read accumulator), so one command's
+ * inputs don't collapse onto another's outputs.
+ */
+export declare function feedExecFrame(args: FeedExecFrameArgs): void;

package/dist/provenance/exec-frame.js

@@ -0,0 +1,49 @@
+/**
+ * Feed a sandbox-server exec provenance frame into the step's
+ * `ProvenanceCollector`.
+ *
+ * Frame paths are absolute container paths under the analysis resource
+ * mount (`/{resourceId}/...`). This helper strips the mount prefix to
+ * analysis-relative (`data/...`, `runs/{runId}/{stepId}/...`,
+ * `runs/{priorRunId}/...`) so `classifyReadPath` and the collector's
+ * `stepPrefix` normalization see the shapes they expect.
+ *
+ * Degrades safely: a disabled or absent frame records the command with no
+ * inputs and no writes (its outputs fall back to leaves at registration).
+ * It never throws — provenance is best-effort and must not fail an exec.
+ */
+import { classifyReadPath } from "./collector.js";
+/** Strip the `/{resourceId}/` mount prefix from an absolute frame path. */
+export function stripMountPrefix(mountRoot, absPath) {
+    const prefix = mountRoot.endsWith("/") ? mountRoot : `${mountRoot}/`;
+    return absPath.startsWith(prefix) ? absPath.slice(prefix.length) : absPath;
+}
+/**
+ * Translate one exec's frame into a collector record. Per-command input
+ * scoping: only the reads observed for THIS exec are attached to its
+ * outputs (not the step's global read accumulator), so one command's
+ * inputs don't collapse onto another's outputs.
+ */
+export function feedExecFrame(args) {
+    const { collector, mountRoot, command, exitCode, durationMs, provenance } = args;
+    const cmd = command[0] ?? "";
+    const cmdArgs = command.slice(1);
+    const code = exitCode ?? -1;
+    const duration = durationMs ?? 0;
+    if (!provenance || provenance.disabled) {
+        collector.recordCommandExecution(cmd, [...cmdArgs], code, duration, [], undefined, []);
+        return;
+    }
+    const commandReads = [];
+    for (const read of provenance.reads) {
+        const rel = stripMountPrefix(mountRoot, read.path);
+        const context = classifyReadPath(rel, collector.stepId, collector.runId, collector.dependsOn);
+        commandReads.push(collector.trackInputAccess(mountRoot, rel, null, context));
+    }
+    const writes = provenance.writes.map((w) => ({
+        path: stripMountPrefix(mountRoot, w.path),
+        hash: "",
+        size: 0,
+    }));
+    collector.recordCommandExecution(cmd, [...cmdArgs], code, duration, writes, undefined, commandReads);
+}

package/dist/provenance/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Unified provenance types for tracking artifact lineage.
+ *
+ * Each output artifact gets a ProvenanceRecord that captures:
+ *   - What produced it (file tool write or sandbox command)
+ *   - What inputs it consumed (lineage chain)
+ *   - What script generated it (if any)
+ */
+import { z } from "zod";
+/** File tool write (write_file, edit_file). */
+export declare const FileToolProducerSchema: z.ZodObject<{
+    type: z.ZodLiteral<"file_tool">;
+    tool: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+/** Sandbox command execution (execute_command). */
+export declare const CommandProducerSchema: z.ZodObject<{
+    type: z.ZodLiteral<"command">;
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exitCode: z.ZodNumber;
+    durationMs: z.ZodNumber;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export declare const ProducerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"file_tool">;
+    tool: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"command">;
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exitCode: z.ZodNumber;
+    durationMs: z.ZodNumber;
+    timestamp: z.ZodString;
+}, z.core.$strip>], "type">;
+export type Producer = z.infer<typeof ProducerSchema>;
+/** Classification of an input source based on mount semantics. */
+export declare const InputSourceSchema: z.ZodEnum<{
+    data: "data";
+    upstream: "upstream";
+    prior: "prior";
+    artifacts: "artifacts";
+}>;
+export type InputSource = z.infer<typeof InputSourceSchema>;
+/** A single input reference in a lineage chain. */
+export declare const InputRefSchema: z.ZodObject<{
+    path: z.ZodString;
+    hash: z.ZodString;
+    source: z.ZodEnum<{
+        data: "data";
+        upstream: "upstream";
+        prior: "prior";
+        artifacts: "artifacts";
+    }>;
+    stepId: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+    fileId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type InputRef = z.infer<typeof InputRefSchema>;
+/** Provenance record for a single output artifact. */
+export declare const ProvenanceRecordSchema: z.ZodObject<{
+    outputPath: z.ZodString;
+    outputHash: z.ZodString;
+    outputSize: z.ZodNumber;
+    producer: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"file_tool">;
+        tool: z.ZodString;
+        timestamp: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"command">;
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exitCode: z.ZodNumber;
+        durationMs: z.ZodNumber;
+        timestamp: z.ZodString;
+    }, z.core.$strip>], "type">;
+    inputs: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        hash: z.ZodString;
+        source: z.ZodEnum<{
+            data: "data";
+            upstream: "upstream";
+            prior: "prior";
+            artifacts: "artifacts";
+        }>;
+        stepId: z.ZodOptional<z.ZodString>;
+        runId: z.ZodOptional<z.ZodString>;
+        fileId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    scriptPath: z.ZodNullable<z.ZodString>;
+    stepId: z.ZodString;
+    runId: z.ZodString;
+}, z.core.$strip>;
+export type ProvenanceRecord = z.infer<typeof ProvenanceRecordSchema>;

package/dist/provenance/types.js

@@ -0,0 +1,64 @@
+/**
+ * Unified provenance types for tracking artifact lineage.
+ *
+ * Each output artifact gets a ProvenanceRecord that captures:
+ *   - What produced it (file tool write or sandbox command)
+ *   - What inputs it consumed (lineage chain)
+ *   - What script generated it (if any)
+ */
+import { z } from "zod";
+// ── Producer ────────────────────────────────────────────────────────
+/** File tool write (write_file, edit_file). */
+export const FileToolProducerSchema = z.object({
+    type: z.literal("file_tool"),
+    tool: z.string(),
+    timestamp: z.string(),
+});
+/** Sandbox command execution (execute_command). */
+export const CommandProducerSchema = z.object({
+    type: z.literal("command"),
+    command: z.string(),
+    args: z.array(z.string()).optional(),
+    exitCode: z.number(),
+    durationMs: z.number(),
+    timestamp: z.string(),
+});
+export const ProducerSchema = z.discriminatedUnion("type", [FileToolProducerSchema, CommandProducerSchema]);
+// ── InputRef ────────────────────────────────────────────────────────
+/** Classification of an input source based on mount semantics. */
+export const InputSourceSchema = z.enum(["data", "upstream", "prior", "artifacts"]);
+/** A single input reference in a lineage chain. */
+export const InputRefSchema = z.object({
+    /** Mount-relative path: /data/counts.csv, /upstream/de/output/results.csv */
+    path: z.string(),
+    /** SHA-256 hash at read time. */
+    hash: z.string(),
+    /** Source classification derived from mount path. */
+    source: InputSourceSchema,
+    /** Step ID that produced this input (absent for data inputs). */
+    stepId: z.string().optional(),
+    /** Run ID that produced this input (absent for data inputs). */
+    runId: z.string().optional(),
+    /** S3 file identity for input files (source: "data"). */
+    fileId: z.string().optional(),
+});
+// ── ProvenanceRecord ────────────────────────────────────────────────
+/** Provenance record for a single output artifact. */
+export const ProvenanceRecordSchema = z.object({
+    /** Path relative to /artifacts. */
+    outputPath: z.string(),
+    /** SHA-256 hash of the output. */
+    outputHash: z.string(),
+    /** Size in bytes. */
+    outputSize: z.number(),
+    /** How this artifact was produced. */
+    producer: ProducerSchema,
+    /** Input files consumed to produce this artifact. */
+    inputs: z.array(InputRefSchema),
+    /** Path to the script that produced this, if identifiable. */
+    scriptPath: z.string().nullable(),
+    /** Workflow step that produced this artifact. */
+    stepId: z.string(),
+    /** Workflow run ID. */
+    runId: z.string(),
+});

package/dist/providers/__fixtures__/session.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Test-only harness `RequestSession` builder. Not a `*.test.ts` file, so the test
+ * runner ignores it; imported by harness unit tests that need a session but never
+ * read its (opaque) auth. The auth is the trivial local one — the harness never
+ * inspects it. Managed-adapter tests that exercise `getAuth` / the managed seams
+ * use the managed builder in `compose/__fixtures__/session.ts` instead.
+ */
+import type { RequestSession, Scope } from "../../auth/types.js";
+export interface SessionOverrides {
+    user?: string;
+    scope?: Scope;
+    agentId?: string;
+    callPath?: readonly string[];
+}
+/** Build a fully-populated harness `RequestSession` for tests, with per-field overrides. */
+export declare function makeSession(overrides?: SessionOverrides): RequestSession;

package/dist/providers/__fixtures__/session.js

@@ -0,0 +1,20 @@
+/**
+ * Test-only harness `RequestSession` builder. Not a `*.test.ts` file, so the test
+ * runner ignores it; imported by harness unit tests that need a session but never
+ * read its (opaque) auth. The auth is the trivial local one — the harness never
+ * inspects it. Managed-adapter tests that exercise `getAuth` / the managed seams
+ * use the managed builder in `compose/__fixtures__/session.ts` instead.
+ */
+import { makeLocalAuth } from "../../auth/local-auth-context.js";
+/** Build a fully-populated harness `RequestSession` for tests, with per-field overrides. */
+export function makeSession(overrides = {}) {
+    return {
+        identity: { user: overrides.user ?? "user-001" },
+        scope: overrides.scope ?? { kind: "analysis", analysisId: "analysis-001" },
+        provenance: {
+            agentId: overrides.agentId ?? "conversation-agent",
+            callPath: overrides.callPath ?? ["conversation-agent"],
+        },
+        auth: makeLocalAuth(),
+    };
+}

package/dist/providers/ai-sdk.d.ts

@@ -0,0 +1,47 @@
+import { type LanguageModel } from "ai";
+import type { ResolveBilling } from "../billing/resolver.js";
+import type { ChatProvider, FetchLike, ProviderCapabilities } from "./types.js";
+export interface AiSdkProviderDeps {
+    readonly model: LanguageModel;
+    readonly resolveBilling: ResolveBilling;
+    readonly capabilities?: Partial<ProviderCapabilities>;
+}
+/**
+ * Connection + model configuration for one `ChatProvider`, discriminated by
+ * wire protocol (`anthropic` | `openai-compatible`). The `model` is the wire
+ * model bound into the provider at construction: `ChatRequest` carries no model
+ * field (see `./types.ts`), so a config value describes exactly one model over
+ * one connection. An embedder running distinct models builds one provider per
+ * model from configs that share the connection (same `baseURL`/`apiKey`) and
+ * differ only in `model` — a single provider cannot be retargeted to another
+ * model per request.
+ */
+export type AiSdkProviderConfig = {
+    readonly kind: "anthropic";
+    readonly baseURL?: string;
+    readonly apiKey: string;
+    readonly model: string;
+    readonly fetch?: FetchLike;
+    readonly capabilities?: Partial<ProviderCapabilities>;
+} | {
+    readonly kind: "openai-compatible";
+    readonly name: string;
+    readonly baseURL: string;
+    readonly apiKey?: string;
+    readonly model: string;
+    readonly fetch?: FetchLike;
+    readonly capabilities?: Partial<ProviderCapabilities>;
+};
+export interface ConfiguredAiSdkProviderDeps {
+    readonly config: AiSdkProviderConfig;
+    readonly resolveBilling: ResolveBilling;
+}
+export declare function createAiSdkProvider(deps: AiSdkProviderDeps): ChatProvider;
+/**
+ * Realize an `AiSdkProviderConfig` into a `ChatProvider` bound to that config's
+ * connection and model. The model is closed into the returned provider here (it
+ * is never passed per `ChatRequest`), so N models require N provider
+ * instances over one shared connection configuration — one instance serves the
+ * single model it was built with.
+ */
+export declare function createConfiguredAiSdkProvider(deps: ConfiguredAiSdkProviderDeps): ChatProvider;