@fevex/core 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/artifacts-gUzemET7.mjs

@@ -0,0 +1,440 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+//#region src/artifacts/artifacts.ts
+var ArtifactError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "ArtifactError";
+		this.code = code;
+	}
+};
+const TENANT_PATTERN = /^[A-Za-z0-9._-]{1,128}$/u;
+const ARTIFACT_ID_PATTERN = /^[A-Za-z0-9_-]{8,128}$/u;
+/** Resolves and validates the tenant scope used by stores and catalogs. */
+function artifactTenantId(context) {
+	const tenantId = context?.tenantId ?? "default";
+	if (typeof tenantId !== "string" || !TENANT_PATTERN.test(tenantId) || tenantId === "." || tenantId === "..") throw new ArtifactError("ARTIFACT_INVALID_CONTEXT", "Artifact tenantId must contain only letters, numbers, dot, underscore or hyphen");
+	return tenantId;
+}
+/** Validates an artifact id before using it in a query or storage key. */
+function assertArtifactId(artifactId) {
+	if (typeof artifactId !== "string" || !ARTIFACT_ID_PATTERN.test(artifactId)) throw new ArtifactError("ARTIFACT_INVALID_ID", "Artifact id is not valid");
+}
+//#endregion
+//#region src/artifacts/internal.ts
+const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+const MIME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*$/;
+function resolveLimits(options = {}) {
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+	if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) throw new ArtifactError("ARTIFACT_INVALID_INPUT", "Artifact maxBytes must be a non-negative integer");
+	if (options.retentionMs !== void 0 && (!Number.isFinite(options.retentionMs) || options.retentionMs < 0)) throw new ArtifactError("ARTIFACT_INVALID_INPUT", "Artifact retentionMs must be a non-negative number");
+	return {
+		...options,
+		maxBytes
+	};
+}
+function assertArtifactWrite(input, limits) {
+	if (!input || typeof input !== "object") throw new ArtifactError("ARTIFACT_INVALID_INPUT", "Artifact write input must be an object");
+	if (typeof input.filename !== "string" || input.filename.trim().length === 0 || input.filename.length > 255 || /[\\/\0]/u.test(input.filename)) throw new ArtifactError("ARTIFACT_INVALID_INPUT", "Artifact filename must be a non-empty display name without path separators");
+	if (typeof input.mimeType !== "string" || !MIME_PATTERN.test(input.mimeType)) throw new ArtifactError("ARTIFACT_INVALID_INPUT", "Artifact mimeType must be a valid MIME type");
+	if (!(input.bytes instanceof Uint8Array)) throw new ArtifactError("ARTIFACT_INVALID_INPUT", "Artifact bytes must be a Uint8Array");
+	if (input.bytes.byteLength > (limits.maxBytes ?? DEFAULT_MAX_BYTES)) throw new ArtifactError("ARTIFACT_TOO_LARGE", `Artifact exceeds the ${limits.maxBytes ?? DEFAULT_MAX_BYTES} byte limit`);
+	if (limits.allowedMimeTypes !== void 0 && !limits.allowedMimeTypes.some((mimeType) => mimeType.toLowerCase() === input.mimeType.toLowerCase())) throw new ArtifactError("ARTIFACT_MIME_UNSUPPORTED", `Artifact MIME type "${input.mimeType}" is not allowed`);
+	if (input.expiresAt !== void 0 && Number.isNaN(Date.parse(input.expiresAt))) throw new ArtifactError("ARTIFACT_INVALID_INPUT", "Artifact expiresAt must be a valid ISO date");
+	if (input.metadata !== void 0 && !isJsonObject(input.metadata)) throw new ArtifactError("ARTIFACT_INVALID_INPUT", "Artifact metadata must be a JSON object");
+}
+function createDescriptor(input, limits) {
+	const artifactId = randomUUID();
+	const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+	const expiresAt = input.expiresAt ?? (limits.retentionMs === void 0 ? void 0 : new Date(Date.now() + limits.retentionMs).toISOString());
+	return {
+		artifactId,
+		uri: `artifact://${artifactId}`,
+		filename: input.filename,
+		mimeType: input.mimeType,
+		size: input.bytes.byteLength,
+		sha256: createHash("sha256").update(input.bytes).digest("hex"),
+		createdAt,
+		...expiresAt === void 0 ? {} : { expiresAt },
+		...input.metadata === void 0 ? {} : { metadata: structuredClone(input.metadata) }
+	};
+}
+function assertNotAborted(context) {
+	context?.signal?.throwIfAborted();
+}
+function isExpired$1(descriptor) {
+	return descriptor.expiresAt !== void 0 && Date.parse(descriptor.expiresAt) <= Date.now();
+}
+function copyBytes(bytes) {
+	return new Uint8Array(bytes);
+}
+function parseDescriptor(value) {
+	let parsed;
+	try {
+		parsed = JSON.parse(value);
+	} catch {
+		throw new ArtifactError("ARTIFACT_CORRUPT", "Artifact metadata is not valid JSON");
+	}
+	if (!isJsonObject(parsed) || typeof parsed.artifactId !== "string" || typeof parsed.uri !== "string" || typeof parsed.filename !== "string" || typeof parsed.mimeType !== "string" || typeof parsed.size !== "number" || typeof parsed.sha256 !== "string" || typeof parsed.createdAt !== "string") throw new ArtifactError("ARTIFACT_CORRUPT", "Artifact metadata is malformed");
+	return parsed;
+}
+function isJsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/artifacts/cataloged-artifact-store.ts
+/**
+* Composes a byte store with a queryable metadata catalog.
+*
+* `put` writes bytes first and then indexes metadata. If indexing fails, the
+* bytes are deleted so the catalog never points at a half-written artifact.
+*/
+var CatalogedArtifactStore = class {
+	#store;
+	#catalog;
+	constructor(options) {
+		this.#store = options.store;
+		this.#catalog = options.catalog;
+	}
+	async put(input, context) {
+		const descriptor = await this.#store.put(input, context);
+		try {
+			await this.#catalog.save(this.#record(descriptor, context), context);
+		} catch (error) {
+			await this.#store.delete?.(descriptor.artifactId, context);
+			throw error;
+		}
+		return descriptor;
+	}
+	async get(artifactId, context) {
+		assertNotAborted(context);
+		assertArtifactId(artifactId);
+		if (!await this.#catalog.get(artifactId, context)) return null;
+		const content = await this.#store.get(artifactId, context);
+		if (!content) throw new ArtifactError("ARTIFACT_CORRUPT", `Artifact "${artifactId}" is indexed but its bytes are missing`);
+		return content;
+	}
+	async head(artifactId, context) {
+		assertNotAborted(context);
+		assertArtifactId(artifactId);
+		return (await this.#catalog.get(artifactId, context))?.descriptor ?? null;
+	}
+	async delete(artifactId, context) {
+		assertNotAborted(context);
+		assertArtifactId(artifactId);
+		const existed = await this.#catalog.get(artifactId, context) !== null;
+		await this.#catalog.delete(artifactId, context);
+		await this.#store.delete?.(artifactId, context);
+		return existed;
+	}
+	async list(query = {}, context) {
+		assertNotAborted(context);
+		return this.#catalog.list(query, context);
+	}
+	async deleteByRun(runId, context) {
+		assertNotAborted(context);
+		if (typeof runId !== "string" || runId.length === 0) throw new ArtifactError("ARTIFACT_INVALID_INPUT", "Artifact runId must be non-empty");
+		let deleted = 0;
+		for (;;) {
+			const records = await this.#catalog.list({
+				runId,
+				includeExpired: true,
+				limit: 100
+			}, context);
+			if (records.length === 0) break;
+			for (const record of records) {
+				await this.delete(record.descriptor.artifactId, context);
+				deleted += 1;
+			}
+		}
+		return deleted;
+	}
+	#record(descriptor, context) {
+		return {
+			descriptor,
+			tenantId: artifactTenantId(context),
+			...context?.runId === void 0 ? {} : { runId: context.runId },
+			...context?.sessionId === void 0 ? {} : { sessionId: context.sessionId },
+			...context?.actor?.id === void 0 ? {} : { actorId: context.actor.id }
+		};
+	}
+};
+//#endregion
+//#region src/artifacts/file-system-artifact-store.ts
+/**
+* Local filesystem artifact store.
+*
+* Layout:
+*   <rootDir>/tenants/<tenantId>/artifacts/<artifactId>
+*   <rootDir>/tenants/<tenantId>/artifacts/<artifactId>.json
+*
+* Bytes are written before metadata, and both use an atomic rename. This is
+* intended for local development and single-node deployments; use
+* `S3ArtifactStore` for multi-instance production.
+*/
+var FileSystemArtifactStore = class {
+	#rootDir;
+	#limits;
+	constructor(options) {
+		if (typeof options.rootDir !== "string" || !options.rootDir.trim()) throw new ArtifactError("ARTIFACT_INVALID_INPUT", "Artifact rootDir must be non-empty");
+		this.#rootDir = resolve(options.rootDir);
+		this.#limits = resolveLimits(options);
+	}
+	async put(input, context) {
+		assertNotAborted(context);
+		assertArtifactWrite(input, this.#limits);
+		const tenantId = artifactTenantId(context);
+		const descriptor = createDescriptor(input, this.#limits);
+		const dataPath = this.#dataPath(tenantId, descriptor.artifactId);
+		const metadataPath = `${dataPath}.json`;
+		await mkdir(join(this.#rootDir, "tenants", tenantId, "artifacts"), { recursive: true });
+		await writeAtomic(dataPath, input.bytes);
+		try {
+			await writeAtomic(metadataPath, JSON.stringify(descriptor));
+		} catch (error) {
+			await remove(dataPath);
+			throw error;
+		}
+		return structuredClone(descriptor);
+	}
+	async get(artifactId, context) {
+		assertNotAborted(context);
+		assertArtifactId(artifactId);
+		const descriptor = await this.#readDescriptor(artifactTenantId(context), artifactId);
+		if (!descriptor || isExpired$1(descriptor)) return null;
+		try {
+			return {
+				descriptor,
+				bytes: copyBytes(await readFile(this.#dataPath(artifactTenantId(context), artifactId)))
+			};
+		} catch (error) {
+			if (isNotFound(error)) return null;
+			throw error;
+		}
+	}
+	async head(artifactId, context) {
+		assertNotAborted(context);
+		assertArtifactId(artifactId);
+		const descriptor = await this.#readDescriptor(artifactTenantId(context), artifactId);
+		return descriptor && !isExpired$1(descriptor) ? descriptor : null;
+	}
+	async delete(artifactId, context) {
+		assertNotAborted(context);
+		assertArtifactId(artifactId);
+		const tenantId = artifactTenantId(context);
+		const dataPath = this.#dataPath(tenantId, artifactId);
+		const existed = await this.#readDescriptor(tenantId, artifactId) !== null;
+		await remove(dataPath);
+		await remove(`${dataPath}.json`);
+		return existed;
+	}
+	async #readDescriptor(tenantId, artifactId) {
+		try {
+			return parseDescriptor(await readFile(`${this.#dataPath(tenantId, artifactId)}.json`, "utf8"));
+		} catch (error) {
+			if (isNotFound(error)) return null;
+			throw error;
+		}
+	}
+	#dataPath(tenantId, artifactId) {
+		return join(this.#rootDir, "tenants", tenantId, "artifacts", artifactId);
+	}
+};
+async function writeAtomic(path, data) {
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	try {
+		await writeFile(temporary, data);
+		await rename(temporary, path);
+	} catch (error) {
+		await remove(temporary);
+		throw error;
+	}
+}
+async function remove(path) {
+	try {
+		await unlink(path);
+	} catch (error) {
+		if (!isNotFound(error)) throw error;
+	}
+}
+function isNotFound(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+//#endregion
+//#region src/artifacts/in-memory-artifact-catalog.ts
+/** Volatile artifact metadata catalog for tests and local development. */
+var InMemoryArtifactCatalog = class {
+	#records = /* @__PURE__ */ new Map();
+	async save(record, context) {
+		const tenantId = artifactTenantId(context);
+		if (record.tenantId !== tenantId) throw new ArtifactError("ARTIFACT_INVALID_CONTEXT", "Artifact record tenant does not match the store context");
+		assertArtifactId(record.descriptor.artifactId);
+		this.#records.set(key$1(tenantId, record.descriptor.artifactId), structuredClone(record));
+	}
+	async get(artifactId, context) {
+		assertArtifactId(artifactId);
+		const record = this.#records.get(key$1(artifactTenantId(context), artifactId));
+		return record && !isExpired(record) ? structuredClone(record) : null;
+	}
+	async list(query = {}, context) {
+		const tenantId = artifactTenantId(context);
+		const limit = query.limit ?? 100;
+		if (!Number.isSafeInteger(limit) || limit < 1) throw new ArtifactError("ARTIFACT_INVALID_INPUT", "Artifact query limit must be a positive integer");
+		return [...this.#records.values()].filter((record) => record.tenantId === tenantId && (query.includeExpired || !isExpired(record)) && (query.runId === void 0 || record.runId === query.runId) && (query.sessionId === void 0 || record.sessionId === query.sessionId) && (query.actorId === void 0 || record.actorId === query.actorId) && (query.mimeType === void 0 || record.descriptor.mimeType === query.mimeType)).sort((left, right) => right.descriptor.createdAt.localeCompare(left.descriptor.createdAt) || right.descriptor.artifactId.localeCompare(left.descriptor.artifactId)).slice(0, Math.min(limit, 1e3)).map((record) => structuredClone(record));
+	}
+	async delete(artifactId, context) {
+		assertArtifactId(artifactId);
+		return this.#records.delete(key$1(artifactTenantId(context), artifactId));
+	}
+	async deleteByRun(runId, context) {
+		if (typeof runId !== "string" || runId.length === 0) throw new ArtifactError("ARTIFACT_INVALID_INPUT", "Artifact runId must be non-empty");
+		const tenantId = artifactTenantId(context);
+		let deleted = 0;
+		for (const [recordKey, record] of this.#records) if (record.tenantId === tenantId && record.runId === runId) {
+			this.#records.delete(recordKey);
+			deleted += 1;
+		}
+		return deleted;
+	}
+};
+function key$1(tenantId, artifactId) {
+	return `${tenantId}:${artifactId}`;
+}
+function isExpired(record) {
+	return record.descriptor.expiresAt !== void 0 && Date.parse(record.descriptor.expiresAt) <= Date.now();
+}
+//#endregion
+//#region src/artifacts/in-memory-artifact-store.ts
+/** Volatile artifact store for tests and local development. */
+var InMemoryArtifactStore = class {
+	#records = /* @__PURE__ */ new Map();
+	#limits;
+	constructor(options = {}) {
+		this.#limits = resolveLimits(options);
+	}
+	async put(input, context) {
+		assertNotAborted(context);
+		assertArtifactWrite(input, this.#limits);
+		const tenantId = artifactTenantId(context);
+		const descriptor = createDescriptor(input, this.#limits);
+		this.#records.set(key(tenantId, descriptor.artifactId), {
+			tenantId,
+			descriptor: structuredClone(descriptor),
+			bytes: copyBytes(input.bytes)
+		});
+		return structuredClone(descriptor);
+	}
+	async get(artifactId, context) {
+		assertNotAborted(context);
+		assertArtifactId(artifactId);
+		const record = this.#records.get(key(artifactTenantId(context), artifactId));
+		if (!record || isExpired$1(record.descriptor)) return null;
+		return {
+			descriptor: structuredClone(record.descriptor),
+			bytes: copyBytes(record.bytes)
+		};
+	}
+	async head(artifactId, context) {
+		assertNotAborted(context);
+		assertArtifactId(artifactId);
+		const record = this.#records.get(key(artifactTenantId(context), artifactId));
+		return record && !isExpired$1(record.descriptor) ? structuredClone(record.descriptor) : null;
+	}
+	async delete(artifactId, context) {
+		assertNotAborted(context);
+		assertArtifactId(artifactId);
+		return this.#records.delete(key(artifactTenantId(context), artifactId));
+	}
+};
+function key(tenantId, artifactId) {
+	return `${tenantId}:${artifactId}`;
+}
+//#endregion
+//#region src/artifacts/s3-artifact-store.ts
+/**
+* Artifact store for S3-compatible object storage (S3, R2, MinIO, GCS via an
+* S3 gateway, and similar).
+*
+* Bytes are stored at `<prefix>/<tenant>/artifacts/<artifactId>` and metadata
+* in a `.json` sidecar next to them. The bucket should stay private; the host
+* serves downloads through its authenticated API or short-lived signed URLs.
+*/
+var S3ArtifactStore = class {
+	#client;
+	#prefix;
+	#limits;
+	constructor(options) {
+		if (!options.client) throw new ArtifactError("ARTIFACT_INVALID_INPUT", "S3 artifact client is required");
+		this.#client = options.client;
+		this.#prefix = normalizePrefix(options.prefix ?? "fevex");
+		this.#limits = resolveLimits(options);
+	}
+	async put(input, context) {
+		assertNotAborted(context);
+		assertArtifactWrite(input, this.#limits);
+		const descriptor = createDescriptor(input, this.#limits);
+		const dataKey = this.#key(artifactTenantId(context), descriptor.artifactId);
+		const metadataKey = `${dataKey}.json`;
+		await this.#client.putObject({
+			key: dataKey,
+			body: copyBytes(input.bytes),
+			contentType: descriptor.mimeType
+		});
+		try {
+			await this.#client.putObject({
+				key: metadataKey,
+				body: new TextEncoder().encode(JSON.stringify(descriptor)),
+				contentType: "application/json"
+			});
+		} catch (error) {
+			await this.#client.deleteObject({ key: dataKey });
+			throw error;
+		}
+		return structuredClone(descriptor);
+	}
+	async get(artifactId, context) {
+		assertNotAborted(context);
+		assertArtifactId(artifactId);
+		const descriptor = await this.#readDescriptor(artifactTenantId(context), artifactId);
+		if (!descriptor || isExpired$1(descriptor)) return null;
+		const bytes = await this.#client.getObject({ key: this.#key(artifactTenantId(context), artifactId) });
+		if (!bytes) throw new ArtifactError("ARTIFACT_CORRUPT", `Artifact "${artifactId}" metadata exists without bytes`);
+		return {
+			descriptor,
+			bytes: copyBytes(bytes)
+		};
+	}
+	async head(artifactId, context) {
+		assertNotAborted(context);
+		assertArtifactId(artifactId);
+		const descriptor = await this.#readDescriptor(artifactTenantId(context), artifactId);
+		return descriptor && !isExpired$1(descriptor) ? descriptor : null;
+	}
+	async delete(artifactId, context) {
+		assertNotAborted(context);
+		assertArtifactId(artifactId);
+		const tenantId = artifactTenantId(context);
+		const dataKey = this.#key(tenantId, artifactId);
+		const existed = await this.#readDescriptor(tenantId, artifactId) !== null;
+		await this.#client.deleteObject({ key: dataKey });
+		await this.#client.deleteObject({ key: `${dataKey}.json` });
+		return existed;
+	}
+	async #readDescriptor(tenantId, artifactId) {
+		const metadata = await this.#client.getObject({ key: `${this.#key(tenantId, artifactId)}.json` });
+		return metadata ? parseDescriptor(new TextDecoder().decode(metadata)) : null;
+	}
+	#key(tenantId, artifactId) {
+		return `${this.#prefix}/${tenantId}/artifacts/${artifactId}`;
+	}
+};
+function normalizePrefix(prefix) {
+	if (typeof prefix !== "string") throw new ArtifactError("ARTIFACT_INVALID_INPUT", "S3 artifact prefix must be a string");
+	const normalized = prefix.replace(/^\/+|\/+$/gu, "");
+	if (normalized.length === 0 || normalized.split("/").some((segment) => segment.length === 0 || segment === "." || segment === "..")) throw new ArtifactError("ARTIFACT_INVALID_INPUT", "S3 artifact prefix is not valid");
+	return normalized;
+}
+//#endregion
+export { CatalogedArtifactStore as a, assertArtifactId as c, FileSystemArtifactStore as i, InMemoryArtifactStore as n, ArtifactError as o, InMemoryArtifactCatalog as r, artifactTenantId as s, S3ArtifactStore as t };

package/dist/channels/index.d.mts

@@ -1,2 +1,2 @@
-import { a as ChannelDeliveryOptions, c as ChannelEvent, d as ChannelMessage, f as ChannelOutput, h as ChannelRunResult, i as ChannelContext, l as ChannelEventType, m as ChannelRunOptions, n as handleChannelInput, o as ChannelElicitationContext, p as ChannelRunEvent, r as ChannelAdapter, s as ChannelError, t as deliverChannelRun, u as ChannelFailurePhase } from "../index-DyyNLuwO.mjs";
+import { a as ChannelDeliveryOptions, c as ChannelEvent, d as ChannelMessage, f as ChannelOutput, h as ChannelRunResult, i as ChannelContext, l as ChannelEventType, m as ChannelRunOptions, n as handleChannelInput, o as ChannelElicitationContext, p as ChannelRunEvent, r as ChannelAdapter, s as ChannelError, t as deliverChannelRun, u as ChannelFailurePhase } from "../index-DVw0zOc_.mjs";
 export { ChannelAdapter, ChannelContext, ChannelDeliveryOptions, ChannelElicitationContext, ChannelError, ChannelEvent, ChannelEventType, ChannelFailurePhase, ChannelMessage, ChannelOutput, ChannelRunEvent, ChannelRunOptions, ChannelRunResult, deliverChannelRun, handleChannelInput };

package/dist/evals/index.d.mts

@@ -1,7 +1,7 @@
-import { l as JsonValue, o as ExecutionContext, t as AgentEvent } from "../types-CuoRx12Q.mjs";
-import { r as ModelMetadata, s as ModelUsage } from "../index-CTIwrVf9.mjs";
-import { l as TraceCost, t as CostCalculator } from "../index-voIZhQXB.mjs";
-import { t as Fevex } from "../fevex-BoPbZ-Tw.mjs";
+import { l as JsonValue, o as ExecutionContext, t as AgentEvent } from "../types-B8laW1hM.mjs";
+import { r as ModelMetadata, s as ModelUsage } from "../index-BgKFd9yw.mjs";
+import { t as CostCalculator, u as TraceCost } from "../index-CpLDt6Rw.mjs";
+import { t as Fevex } from "../fevex-B4QY5Z6e.mjs";
 //#region src/evals/canonical-json.d.ts
 /** Serializes JSON-like data with stable object-key ordering. */
 declare function serializeCanonical(value: unknown): string;

package/dist/fevex-B4QY5Z6e.d.mts

@@ -0,0 +1,119 @@
+import { F as ArtifactStore, f as RunId, o as ExecutionContext, t as AgentEvent } from "./types-B8laW1hM.mjs";
+import { t as ModelGateway } from "./index-BgKFd9yw.mjs";
+import { B as TeamRun, C as PurgeRunsResult, F as RunStore, I as Session, J as WorkflowRun, L as SessionId, M as RunRequest, N as RunResult, S as PurgeRunsOptions, a as AgentRun, b as ListEventsOptions, f as CredentialStore, j as RunRecord, t as AgentDefinition, w as ResumeRunResolution } from "./index-CzAi2Y_Z.mjs";
+import { r as ContextProvider, s as MemoryStore } from "./index-BJktlD4E.mjs";
+import { i as ObservabilityStats, r as ObservabilityOptions } from "./index-CpLDt6Rw.mjs";
+import { r as Sandbox } from "./index-Df84VWmN.mjs";
+import { g as ToolDefinition, s as ConnectionDefinition } from "./index-5p3q2yIp.mjs";
+import { r as PolicyDefinition } from "./index-CbACw6xZ.mjs";
+import { n as WorkflowDefinition } from "./index-CseuTR-F.mjs";
+import { t as TeamDefinition } from "./index-1cHr7KB_.mjs";
+//#region src/fevex.d.ts
+interface FevexAdmissionRequest {
+  kind: 'agent' | 'workflow' | 'team';
+  name: string;
+  request: RunRequest;
+  activeRuns: number;
+  activeTenantRuns: number;
+}
+/** Optional host-level admission controls applied before a top-level run starts. */
+interface FevexAdmission {
+  /** Maximum concurrent top-level runs in this runtime. */
+  maxActiveRuns?: number;
+  /** Maximum concurrent top-level runs for one tenant. */
+  maxActiveRunsPerTenant?: number;
+  /** Defaults to a non-empty `context.attributes.tenantId` string. */
+  tenantKey?: (context?: ExecutionContext) => string | undefined;
+  /** Custom admission check, called after the built-in limits. */
+  authorize?: (request: FevexAdmissionRequest) => boolean | Promise<boolean>;
+}
+interface FevexShutdownOptions {
+  /**
+   * Maximum time to wait for active runs before cancelling them. Defaults to
+   * 30 seconds. Use `0` to cancel immediately. If the deadline expires,
+   * shutdown allows up to 5 additional seconds for forced cancellation and the
+   * final trace flush.
+   */
+  timeoutMs?: number;
+}
+interface FevexShutdownResult {
+  /** Runs that were still active when the grace period expired. */
+  cancelledRunIds: RunId[];
+  /** True when the grace deadline expired before all active runs finished. */
+  timedOut: boolean;
+  /** Error surfaced while flushing pending traces, if any. */
+  exportError?: unknown;
+  /** Observability counters after the shutdown flush. */
+  observability: ObservabilityStats;
+}
+interface FevexLimits {
+  /**
+   * Maximum non-control events persisted for one run. Control events such as
+   * pause, resume, approval and terminal transitions are always persisted.
+   */
+  maxEventsPerRun?: number;
+}
+/** Provider-neutral definitions and adapters used to create one Fevex runtime. */
+interface FevexConfig {
+  models: Record<string, ModelGateway>;
+  agents: AgentDefinition[];
+  workflows?: WorkflowDefinition[];
+  teams?: TeamDefinition[];
+  tools?: ToolDefinition[];
+  connections?: ConnectionDefinition[];
+  contextProviders?: ContextProvider[];
+  memoryStore?: MemoryStore;
+  runStore?: RunStore;
+  credentialStore?: CredentialStore;
+  sandbox?: Sandbox;
+  /** Optional artifact store exposed to tools as `context.artifacts`. */
+  artifacts?: ArtifactStore;
+  policies?: PolicyDefinition[];
+  onEvent?: (event: AgentEvent) => void;
+  observability?: ObservabilityOptions;
+  admission?: FevexAdmission;
+  limits?: FevexLimits;
+}
+interface Fevex {
+  startAgent<TInput = unknown, TOutput = unknown>(name: string, request: RunRequest<TInput, TOutput>): Promise<AgentRun<TOutput>>;
+  runAgent<TInput = unknown, TOutput = unknown>(name: string, request: RunRequest<TInput, TOutput>): Promise<RunResult<TOutput>>;
+  streamAgent<TInput = unknown, TOutput = unknown>(name: string, request: RunRequest<TInput, TOutput>): AsyncIterable<AgentEvent>;
+  startWorkflow<TInput = unknown, TOutput = unknown>(name: string, request: RunRequest<TInput, TOutput>): Promise<WorkflowRun<TOutput>>;
+  runWorkflow<TInput = unknown, TOutput = unknown>(name: string, request: RunRequest<TInput, TOutput>): Promise<RunResult<TOutput>>;
+  startTeam<TInput = unknown, TOutput = unknown>(name: string, request: RunRequest<TInput, TOutput>): Promise<TeamRun<TOutput>>;
+  runTeam<TInput = unknown, TOutput = unknown>(name: string, request: RunRequest<TInput, TOutput>): Promise<RunResult<TOutput>>;
+  streamTeam<TInput = unknown, TOutput = unknown>(name: string, request: RunRequest<TInput, TOutput>): AsyncIterable<AgentEvent>;
+  getTeamRun<TOutput = unknown>(runId: RunId): Promise<TeamRun<TOutput> | undefined>;
+  getRun<TOutput = unknown>(runId: RunId): Promise<RunRecord<TOutput> | undefined>;
+  listEvents(runId: RunId, options?: ListEventsOptions): Promise<AgentEvent[]>;
+  cancelRun(runId: RunId): Promise<boolean>;
+  resumeRun<TOutput = unknown>(runId: RunId, resolution: ResumeRunResolution): Promise<RunRecord<TOutput>>;
+  recoverRun<TOutput = unknown>(runId: RunId, options: {
+    actor: {
+      id: string;
+      type?: string;
+    };
+  }): Promise<RunRecord<TOutput>>;
+  purgeRuns(options?: PurgeRunsOptions): Promise<PurgeRunsResult>;
+  compactSession(sessionId: SessionId, summary: string): Promise<Session>;
+  /** Waits for queued exports and rejects with failures accumulated since the previous flush. */
+  flushObservability(options?: {
+    timeoutMs?: number;
+  }): Promise<void>;
+  /** Cumulative trace export counters for this runtime. */
+  getObservabilityStats(): ObservabilityStats;
+  /**
+   * Stops admitting new work, drains or cancels active runs, and flushes trace
+   * exports. The host still owns closing its stores and external adapters.
+   */
+  shutdown(options?: FevexShutdownOptions): Promise<FevexShutdownResult>;
+}
+/**
+ * Validates a configuration snapshot and creates an isolated runtime.
+ *
+ * The runtime does not own external adapters; callers remain responsible for
+ * closing model, connection, store, and exporter resources they provide.
+ */
+declare function createFevex(config: FevexConfig): Fevex;
+//#endregion
+export { FevexLimits as a, createFevex as c, FevexConfig as i, FevexAdmission as n, FevexShutdownOptions as o, FevexAdmissionRequest as r, FevexShutdownResult as s, Fevex as t };

package/dist/http/index.d.mts

@@ -1,7 +1,7 @@
-import { l as JsonValue, o as ExecutionContext, t as AgentEvent } from "../types-CuoRx12Q.mjs";
-import { c as ReasoningEffort } from "../index-CTIwrVf9.mjs";
-import { E as RunRecord, F as TeamRun, M as SessionId, U as WorkflowRun, a as AgentRun } from "../index-CaE864Kz.mjs";
-import { t as Fevex } from "../fevex-BoPbZ-Tw.mjs";
+import { D as ArtifactCatalog, F as ArtifactStore, f as RunId, k as ArtifactDescriptor, l as JsonValue, o as ExecutionContext, t as AgentEvent } from "../types-B8laW1hM.mjs";
+import { c as ReasoningEffort } from "../index-BgKFd9yw.mjs";
+import { B as TeamRun, J as WorkflowRun, L as SessionId, a as AgentRun, j as RunRecord } from "../index-CzAi2Y_Z.mjs";
+import { t as Fevex } from "../fevex-B4QY5Z6e.mjs";
 //#region src/http/protocol.d.ts
 declare const FEVEX_HTTP_PROTOCOL_VERSION = "3";
 declare const FEVEX_HTTP_PROTOCOL_VERSION_HEADER = "Fevex-Protocol-Version";
@@ -10,6 +10,8 @@ interface StartRunHttpRequest<TInput extends JsonValue = JsonValue> {
   model?: string;
   reasoning?: ReasoningEffort;
   sessionId?: SessionId;
+  /** Maximum wall-clock time for the run, including time spent paused. */
+  deadlineMs?: number;
 }
 type ResumeRunHttpRequest = {
   type: 'elicitation';
@@ -47,11 +49,66 @@ interface FevexProblemDetails {
 interface FevexHttpHandlerContext {
   context?: ExecutionContext;
 }
+/** Host-facing resource access check. */
+type FevexHttpAccess = {
+  action: 'start';
+  kind: 'agent' | 'workflow' | 'team';
+  name: string;
+  sessionId?: SessionId;
+  context?: ExecutionContext;
+} | {
+  action: 'read' | 'observe' | 'cancel' | 'resume' | 'recover';
+  runId: RunId;
+  context?: ExecutionContext;
+};
+/** Host-facing artifact access check. */
+type FevexArtifactAccess = {
+  action: 'read' | 'delete';
+  kind: 'artifact';
+  artifactId: string;
+  context?: ExecutionContext;
+} | {
+  action: 'read';
+  kind: 'artifacts';
+  runId: RunId;
+  context?: ExecutionContext;
+};
 interface FevexHttpHandlerOptions {
   fevex: Fevex;
   pollIntervalMs?: number;
   /** Events per SSE read (default 100, maximum 1000). */
   eventPageSize?: number;
+  /** Maximum concurrent SSE streams (default unlimited). */
+  maxConnections?: number;
+  /**
+   * Authorizes a resource operation before the handler reads or mutates a run,
+   * or starts a run (new or existing session). Return false for a 403 response.
+   * Omit to preserve the host's existing trusted-network behavior.
+   */
+  authorize?: (access: FevexHttpAccess) => boolean | Promise<boolean>;
+  /**
+   * Byte store used by the artifact routes. When omitted, artifact routes
+   * return 501.
+   */
+  artifacts?: ArtifactStore;
+  /**
+   * Metadata catalog used to list artifacts for a run. When omitted, the
+   * run-artifact listing route returns 501.
+   */
+  artifactCatalog?: ArtifactCatalog;
+  /**
+   * Authorizes artifact reads, listings and deletions. Omit to preserve the
+   * host's existing trusted-network behavior.
+   */
+  authorizeArtifact?: (access: FevexArtifactAccess) => boolean | Promise<boolean>;
+  /**
+   * Called after a run starts so the host can persist run and session ownership.
+   * If it throws, the handler cancels the new run and returns 500. A process
+   * crash between start and this callback leaves the run unowned; hosts must
+   * treat unowned runs as inaccessible. Runs created outside the HTTP handler
+   * are not reported.
+   */
+  onRunStarted?: (run: RunRecord, context?: ExecutionContext) => void | Promise<void>;
   onError?: (error: unknown, problem: FevexProblemDetails) => void;
 }
 type FevexHttpHandler = (request: Request, context?: FevexHttpHandlerContext) => Promise<Response>;
@@ -73,6 +130,9 @@ interface FevexHttpClient {
   resumeRun<TOutput = JsonValue>(runId: string, request: ResumeRunHttpRequest): Promise<RunRecord<TOutput>>;
   recoverRun<TOutput = JsonValue>(runId: string): Promise<RunRecord<TOutput>>;
   cancelRun(runId: string): Promise<void>;
+  getArtifact(artifactId: string): Promise<Response>;
+  listArtifacts(runId: string): Promise<ArtifactDescriptor[]>;
+  deleteArtifact(artifactId: string): Promise<void>;
 }
 //#endregion
 //#region src/http/transport.d.ts
@@ -87,4 +147,4 @@ declare class FevexHttpError extends Error {
 }
 declare function createFevexHttpClient(options: FevexHttpClientOptions): FevexHttpClient;
 //#endregion
-export { FEVEX_HTTP_PROTOCOL_VERSION, FEVEX_HTTP_PROTOCOL_VERSION_HEADER, FevexHttpClient, FevexHttpClientOptions, FevexHttpError, FevexHttpFetch, FevexHttpHandler, FevexHttpHandlerContext, FevexHttpHandlerOptions, FevexProblemDetails, ObserveRunOptions, ResumeRunHttpRequest, StartRunHttpRequest, createFevexHttpClient, createFevexHttpHandler };
+export { FEVEX_HTTP_PROTOCOL_VERSION, FEVEX_HTTP_PROTOCOL_VERSION_HEADER, FevexArtifactAccess, FevexHttpAccess, FevexHttpClient, FevexHttpClientOptions, FevexHttpError, FevexHttpFetch, FevexHttpHandler, FevexHttpHandlerContext, FevexHttpHandlerOptions, FevexProblemDetails, ObserveRunOptions, ResumeRunHttpRequest, StartRunHttpRequest, createFevexHttpClient, createFevexHttpHandler };