@fevex/core 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/channels/index.mjs

@@ -1,17 +1,20 @@
+import { n as RunPausedError } from "../run-error-Cr17wPGH.mjs";
 //#region src/channels/channel.ts
 var ChannelError = class extends Error {
 	code;
 	safeMessage;
 	name = "ChannelError";
+	runId;
 	constructor(code, safeMessage, options) {
 		super(safeMessage, options);
 		this.code = code;
 		this.safeMessage = safeMessage;
+		this.runId = options?.runId;
 	}
 };
 //#endregion
 //#region src/channels/handle-channel-input.ts
-/** Parses one channel input, runs the configured agent, and delivers its output. */
+/** Parses one channel input, runs the configured agent, and delivers its result or elicitation. */
 async function handleChannelInput(input, options) {
 	const channelEvents = [];
 	const emit = (event) => {
@@ -32,57 +35,92 @@ async function handleChannelInput(input, options) {
 	};
 	const message = parsed;
 	emit(received(options.adapter.name, message));
-	let result;
+	let runId;
 	try {
 		const sessionId = await options.resolveSessionId?.(message);
-		result = await options.fevex.runAgent(options.agentName, {
+		runId = (await options.fevex.runAgent(options.agentName, {
 			input: message.content,
 			...sessionId ? { sessionId } : {},
 			context: channelContext(options.adapter.name, message),
 			signal: options.signal
-		});
+		})).runId;
 	} catch (cause) {
-		const error = channelError("CHANNEL_RUN_FAILED", "Channel run failed", cause);
-		emit(failed(options.adapter.name, "run", error, message));
-		throw error;
+		if (cause instanceof RunPausedError && cause.pause.type === "elicitation") runId = cause.runId;
+		else {
+			const error = channelError("CHANNEL_RUN_FAILED", "Channel run failed", cause);
+			emit(failed(options.adapter.name, "run", error, message));
+			throw error;
+		}
 	}
-	const run = await options.fevex.getRun(result.runId);
-	if (!run || run.kind === "workflow" || run.kind === "team") {
-		const error = channelError("CHANNEL_RUN_FAILED", "Channel run was not found after completion");
-		emit(failed(options.adapter.name, "run", error, message));
+	const delivered = await deliverChannelRun(runId, message, options);
+	return {
+		...delivered,
+		events: [channelEvents[0], ...delivered.events]
+	};
+}
+/** Delivers a stored agent result or elicitation without executing the agent again. */
+async function deliverChannelRun(runId, message, options) {
+	options.signal?.throwIfAborted();
+	const run = await options.fevex.getRun(runId);
+	const elicitation = run?.status === "paused" && run.pause?.type === "elicitation" ? run.pause.request : void 0;
+	if (!run || run.kind === "workflow" || run.kind === "team" || run.status !== "completed" && !elicitation) {
+		const error = channelError("CHANNEL_RUN_FAILED", "Channel run is not ready for delivery", void 0, runId);
+		options.onEvent?.(failed(options.adapter.name, "run", error, message));
 		throw error;
 	}
 	const output = {
-		deliveryId: message.deliveryId,
+		deliveryId: elicitation ? `elicitation:${runId}:${elicitation.id}` : message.deliveryId,
 		conversationId: message.conversationId,
 		...message.threadId ? { threadId: message.threadId } : {},
-		content: stringifyOutput(result.output),
+		content: elicitation ? elicitation.prompt : stringifyOutput(run.output ?? null),
 		metadata: {
-			runId: result.runId,
-			sessionId: result.sessionId
+			runId,
+			sessionId: run.sessionId,
+			...elicitation ? { requestId: elicitation.id } : {}
 		}
 	};
 	let delivery;
 	try {
-		delivery = await options.adapter.deliver(output, { signal: options.signal });
+		if (elicitation) {
+			if (!options.adapter.deliverElicitation) throw channelError("CHANNEL_ELICITATION_UNSUPPORTED", "Channel does not support elicitation delivery", void 0, runId);
+			if (elicitation.expiresAt && Date.now() > Date.parse(elicitation.expiresAt)) throw channelError("CHANNEL_ELICITATION_EXPIRED", "Channel elicitation has expired", void 0, runId);
+			delivery = await options.adapter.deliverElicitation(elicitation, {
+				signal: options.signal,
+				deliveryId: output.deliveryId,
+				runId,
+				sessionId: run.sessionId,
+				conversationId: message.conversationId,
+				...message.threadId ? { threadId: message.threadId } : {}
+			});
+		} else delivery = await options.adapter.deliver(output, { signal: options.signal });
 	} catch (cause) {
-		const error = channelError("CHANNEL_DELIVERY_FAILED", "Channel delivery failed", cause);
-		emit(failed(options.adapter.name, "deliver", error, message));
+		const error = cause instanceof ChannelError ? channelError(cause.code, cause.safeMessage, cause, runId) : channelError("CHANNEL_DELIVERY_FAILED", "Channel delivery failed", cause, runId);
+		options.onEvent?.({
+			...failed(options.adapter.name, "deliver", error, {
+				...message,
+				deliveryId: output.deliveryId
+			}),
+			...elicitation ? { requestId: elicitation.id } : {}
+		});
 		throw error;
 	}
-	const deliveredEvent = delivered(options.adapter.name, message);
-	emit(deliveredEvent);
+	const deliveredEvent = {
+		...delivered(options.adapter.name, {
+			...message,
+			deliveryId: output.deliveryId
+		}),
+		runId,
+		...elicitation ? { requestId: elicitation.id } : {}
+	};
+	options.onEvent?.(deliveredEvent);
 	return {
 		ignored: false,
 		message,
 		run,
 		output,
 		delivery,
-		events: [
-			channelEvents[0],
-			...result.events ?? [],
-			deliveredEvent
-		]
+		...elicitation ? { elicitation } : {},
+		events: [...await options.fevex.listEvents(runId), deliveredEvent]
 	};
 }
 function channelContext(adapter, message) {
@@ -132,6 +170,7 @@ function failed(adapter, phase, error, message) {
 		adapter,
 		phase,
 		error: error.safeMessage,
+		...error.runId ? { runId: error.runId } : {},
 		...message ? {
 			messageId: message.id,
 			deliveryId: message.deliveryId,
@@ -140,11 +179,14 @@ function failed(adapter, phase, error, message) {
 		} : {}
 	};
 }
-function channelError(code, safeMessage, cause) {
-	return new ChannelError(code, safeMessage, cause === void 0 ? void 0 : { cause });
+function channelError(code, safeMessage, cause, runId) {
+	return new ChannelError(code, safeMessage, {
+		...cause === void 0 ? {} : { cause },
+		...runId ? { runId } : {}
+	});
 }
 function stringifyOutput(value) {
 	return typeof value === "string" ? value : JSON.stringify(value);
 }
 //#endregion
-export { ChannelError, handleChannelInput };
+export { ChannelError, 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-B4PIkqOU.mjs";
-import { t as Fevex } from "../fevex-Ddyi6z6L.mjs";
+import { l as JsonValue, o as ExecutionContext, t as AgentEvent } from "../types-BDVUoAU6.mjs";
+import { r as ModelMetadata, s as ModelUsage } from "../index-BPwkgdo3.mjs";
+import { l as TraceCost, t as CostCalculator } from "../index-D6lnI92z.mjs";
+import { t as Fevex } from "../fevex-B5NxFKcV.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-Ddyi6z6L.d.mts → fevex-B5NxFKcV.d.mts}

@@ -1,14 +1,39 @@
-import { f as RunId, t as AgentEvent } from "./types-CuoRx12Q.mjs";
-import { t as ModelGateway } from "./index-CTIwrVf9.mjs";
-import { A as RunStore, D as RunRequest, E as RunRecord, F as TeamRun, M as SessionId, O as RunResult, S as ResumeRunResolution, U as WorkflowRun, a as AgentRun, b as ListEventsOptions, f as CredentialStore, j as Session, t as AgentDefinition } from "./index-Dx_LotWZ.mjs";
-import { r as ContextProvider, s as MemoryStore } from "./index-DeXUtyd9.mjs";
-import { r as ObservabilityOptions } from "./index-B4PIkqOU.mjs";
-import { r as Sandbox } from "./index-CrOId2px.mjs";
-import { g as ToolDefinition, s as ConnectionDefinition } from "./index-CqOjvtQ9.mjs";
-import { r as PolicyDefinition } from "./index-dkFyTNh4.mjs";
-import { n as WorkflowDefinition } from "./index-DviHtsLo.mjs";
-import { t as TeamDefinition } from "./index-Bg9rr8Qe.mjs";
+import { F as ArtifactStore, f as RunId, o as ExecutionContext, t as AgentEvent } from "./types-BDVUoAU6.mjs";
+import { t as ModelGateway } from "./index-BPwkgdo3.mjs";
+import { A as RunRecord, C as PurgeRunsResult, F as Session, I as SessionId, M as RunResult, P as RunStore, S as PurgeRunsOptions, a as AgentRun, b as ListEventsOptions, f as CredentialStore, j as RunRequest, q as WorkflowRun, t as AgentDefinition, w as ResumeRunResolution, z as TeamRun } from "./index-CGmHXV31.mjs";
+import { r as ContextProvider, s as MemoryStore } from "./index-aayvtf0J.mjs";
+import { r as ObservabilityOptions } from "./index-D6lnI92z.mjs";
+import { r as Sandbox } from "./index-BFnWUu7j.mjs";
+import { g as ToolDefinition, s as ConnectionDefinition } from "./index-CKQCNvJz.mjs";
+import { r as PolicyDefinition } from "./index-Cb3AB98n.mjs";
+import { n as WorkflowDefinition } from "./index-Br-zPxZH.mjs";
+import { t as TeamDefinition } from "./index-Dsulk-n6.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 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>;
@@ -22,9 +47,13 @@ interface FevexConfig {
   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>>;
@@ -46,6 +75,7 @@ interface Fevex {
       type?: string;
     };
   }): Promise<RunRecord<TOutput>>;
+  purgeRuns(options?: PurgeRunsOptions): Promise<PurgeRunsResult>;
   compactSession(sessionId: SessionId, summary: string): Promise<Session>;
   flushObservability(): Promise<void>;
 }
@@ -57,4 +87,4 @@ interface Fevex {
  */
 declare function createFevex(config: FevexConfig): Fevex;
 //#endregion
-export { FevexConfig as n, createFevex as r, Fevex as t };
+export { FevexLimits as a, FevexConfig as i, FevexAdmission as n, createFevex as o, FevexAdmissionRequest as r, 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-Dx_LotWZ.mjs";
-import { t as Fevex } from "../fevex-Ddyi6z6L.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-BDVUoAU6.mjs";
+import { c as ReasoningEffort } from "../index-BPwkgdo3.mjs";
+import { A as RunRecord, I as SessionId, a as AgentRun, q as WorkflowRun, z as TeamRun } from "../index-CGmHXV31.mjs";
+import { t as Fevex } from "../fevex-B5NxFKcV.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 };