@fevex/core 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,245 @@
+# Fevex
+
+Agent Engineering Framework for code-first, provider-neutral AI agents in
+TypeScript.
+
+Fevex gives you the small contracts needed to define agents, tools, model
+adapters, validation and tests without adopting a heavy runtime.
+
+> **Status:** early MVP. Fevex is usable for local, single-tool agent runs, but
+> its API may change before the first stable release.
+
+## Why Fevex
+
+- **Provider-neutral:** application code depends on `ModelGateway`, not a model
+  vendor SDK.
+- **Typed tools:** Standard Schema validators infer inputs and validate every
+  runtime boundary.
+- **Small runtime:** one package, ESM, Node.js 20+, no database or service
+  required.
+- **Observable:** successful and failed runs emit structured events.
+- **Testable:** `fevex/testing` includes a deterministic model and shared model
+  contract checks.
+
+## Install
+
+```bash
+npm install fevex
+```
+
+For official model adapters:
+
+```bash
+npm install fevex @fevex/openai
+npm install fevex @fevex/deepseek
+```
+
+Schemas are optional. The examples use Zod 4, but any Standard
+Schema-compatible validator can be used:
+
+```bash
+npm install zod
+```
+
+## Quickstart
+
+This example executes a complete model-tool-model cycle without network access:
+
+```ts
+import { createFevex, defineAgent, defineTool } from 'fevex';
+import { fakeModel } from 'fevex/testing';
+import { z } from 'zod';
+
+const accountInput = z.object({
+  accountId: z.number(),
+});
+
+const accountOutput = z.object({
+  accountId: z.number(),
+  status: z.literal('active'),
+});
+
+const getAccount = defineTool({
+  name: 'accounts.get',
+  description: 'Get an account by ID.',
+  inputSchema: accountInput,
+  outputSchema: accountOutput,
+  execute({ accountId }) {
+    return { accountId, status: 'active' };
+  },
+});
+
+const model = fakeModel(
+  {
+    toolCalls: [{
+      id: 'call-1',
+      name: 'accounts.get',
+      input: { accountId: 42 },
+    }],
+  },
+  { output: 'Account 42 is active.' },
+);
+
+const app = createFevex({
+  models: { default: model },
+  agents: [defineAgent({
+    name: 'support',
+    instructions: 'Answer account questions clearly.',
+    tools: ['accounts.get'],
+    outputSchema: z.string(),
+  })],
+  tools: [getAccount],
+});
+
+const result = await app.runAgent<string, string>('support', {
+  input: 'What is the status of account 42?',
+});
+
+console.log(result.output);
+// Account 42 is active.
+```
+
+`fakeModel` returns its configured responses in order and records every input in
+`model.calls`.
+
+## Connect A Model
+
+Real providers connect through the small `ModelGateway` contract:
+
+```ts
+import type { ModelGateway } from 'fevex/models';
+
+export const model: ModelGateway = {
+  async generate({ messages, tools, outputSchema, signal }) {
+    const response = await yourProvider.generate({
+      messages,
+      tools,
+      outputSchema,
+      signal,
+    });
+
+    return {
+      output: response.output,
+      toolCalls: response.toolCalls,
+      usage: response.usage,
+    };
+  },
+};
+```
+
+Provider integrations remain outside the core package. The first official
+adapter is `@fevex/openai`, authored by Fevex over the native OpenAI HTTP API:
+
+```ts
+import { createOpenAI } from '@fevex/openai';
+
+const model = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY!,
+  organization: process.env.OPENAI_ORG_ID,
+  project: process.env.OPENAI_PROJECT_ID,
+})('gpt-5.6');
+```
+
+DeepSeek follows the same shape:
+
+```ts
+import { createDeepSeek } from '@fevex/deepseek';
+
+const model = createDeepSeek({
+  apiKey: process.env.DEEPSEEK_API_KEY!,
+})('deepseek-chat');
+```
+
+Applications can still implement `ModelGateway` directly as shown above.
+
+## Validation
+
+Fevex accepts
+[`StandardSchemaV1`](https://github.com/standard-schema/standard-schema)
+validators for:
+
+- tool input before `execute`;
+- tool output before it is returned to the model;
+- final agent output before it is returned to the application.
+
+Schemas may transform values. The transformed result must still be JSON-safe.
+The schema passed to `runAgent` takes precedence over the agent schema for that
+run. Plain JSON Schema objects are not executable validators and are not
+accepted by these fields.
+
+When a model adapter needs schemas, Fevex converts authoring schemas that also
+implement Standard JSON Schema into JSON Schema 2020-12 before calling
+`ModelGateway.generate`. Adapters receive transportable JSON Schema in
+`ToolSpec.inputSchema` and `ModelGenerateInput.outputSchema`; they never receive
+the application's executable validators. If a run needs a schema at the model
+boundary and the schema cannot be converted, Fevex fails before invoking the
+model with `SCHEMA_NOT_TRANSPORTABLE`.
+
+Use `testModelGateway` to verify a custom model adapter against the shared
+contract:
+
+```ts
+import { testModelGateway } from 'fevex/testing';
+
+await testModelGateway(model);
+```
+
+## Events
+
+Pass `onEvent` to observe success and failure without wrapping provider or tool
+errors:
+
+```ts
+const app = createFevex({
+  models,
+  agents,
+  tools,
+  onEvent(event) {
+    console.log(event.type, event.runId, event.payload);
+  },
+});
+```
+
+The MVP emits:
+
+```text
+run.started
+model.completed
+tool.completed
+tool.failed
+run.completed
+run.failed
+```
+
+Successful runs also return their events in `RunResult.events`.
+
+## Public Exports
+
+| Import | Purpose |
+| --- | --- |
+| `fevex` | Common runtime, definitions and contracts |
+| `fevex/agents` | Agent definitions |
+| `fevex/models` | Provider-neutral model contracts |
+| `fevex/tools` | Tool definitions and execution context |
+| `fevex/runtime` | Run request and result contracts |
+| `fevex/testing` | Deterministic testing helpers |
+
+All subpaths ship in the same `fevex` package.
+
+## Current Scope
+
+The MVP intentionally supports:
+
+- one model response, or one model-tool-model cycle;
+- an in-memory runtime;
+- synchronous event observers;
+- optional Standard Schema validation;
+- `AbortSignal` cancellation.
+
+It does not yet include streaming, retries, persistence, approvals, a CLI or
+official provider adapters. `AgentDefinition.limits` is reserved and has no
+runtime effect yet.
+
+## License
+
+Apache-2.0

package/dist/agents/index.d.mts

@@ -0,0 +1,23 @@
+import { t as ExactDefinition } from "../exact-definition-NHBBFlFR.mjs";
+import { ModelRef, ReasoningEffort } from "../models/index.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/agents/index.d.ts
+interface AgentLimits {
+  maxSteps?: number;
+  maxToolCalls?: number;
+  maxInputTokens?: number | false;
+  maxOutputTokens?: number | false;
+}
+interface AgentDefinition<TOutput = unknown> {
+  name: string;
+  instructions: string;
+  model?: ModelRef;
+  tools?: string[];
+  reasoning?: ReasoningEffort;
+  modelOptions?: Record<string, unknown>;
+  outputSchema?: StandardSchemaV1<unknown, TOutput>;
+  limits?: AgentLimits;
+}
+declare function defineAgent<T extends AgentDefinition>(agent: ExactDefinition<T, AgentDefinition>): T;
+//#endregion
+export { AgentDefinition, AgentLimits, defineAgent };

package/dist/agents/index.mjs

@@ -0,0 +1,6 @@
+//#region src/agents/index.ts
+function defineAgent(agent) {
+	return agent;
+}
+//#endregion
+export { defineAgent };

package/dist/exact-definition-NHBBFlFR.d.mts

@@ -0,0 +1,4 @@
+//#region src/internal/exact-definition.d.ts
+type ExactDefinition<TInput, TShape> = TInput & { readonly [TKey in Exclude<keyof TInput, keyof TShape>]: never; };
+//#endregion
+export { ExactDefinition as t };

package/dist/index-D_RBJmVt.d.mts

@@ -0,0 +1,44 @@
+//#region src/core/index.d.ts
+type JsonPrimitive = string | number | boolean | null;
+type JsonObject = {
+  [key: string]: JsonValue;
+};
+type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
+type RunId = string;
+declare const SCHEMA_NOT_TRANSPORTABLE = "SCHEMA_NOT_TRANSPORTABLE";
+interface ExecutionContext {
+  namespace?: string;
+  actor?: {
+    id: string;
+    type?: string;
+  };
+  attributes?: JsonObject;
+  prompt?: JsonObject;
+}
+type AgentMessageRole = 'system' | 'user' | 'assistant' | 'tool';
+interface AgentMessage {
+  role: AgentMessageRole;
+  content: string;
+  name?: string;
+  toolCallId?: string;
+  toolCalls?: ToolCall[];
+}
+interface ToolSpec {
+  name: string;
+  description?: string;
+  inputSchema?: JsonObject;
+}
+interface ToolCall {
+  id: string;
+  name: string;
+  input: JsonValue;
+}
+type AgentEventType = 'run.started' | 'model.completed' | 'tool.completed' | 'tool.failed' | 'run.completed' | 'run.failed';
+interface AgentEvent<TPayload extends JsonValue = JsonObject> {
+  type: AgentEventType;
+  runId: RunId;
+  timestamp: string;
+  payload?: TPayload;
+}
+//#endregion
+export { ExecutionContext as a, JsonValue as c, ToolCall as d, ToolSpec as f, AgentMessageRole as i, RunId as l, AgentEventType as n, JsonObject as o, AgentMessage as r, JsonPrimitive as s, AgentEvent as t, SCHEMA_NOT_TRANSPORTABLE as u };

package/dist/index.d.mts

@@ -0,0 +1,18 @@
+import { a as ExecutionContext, c as JsonValue, d as ToolCall, f as ToolSpec, i as AgentMessageRole, l as RunId, n as AgentEventType, o as JsonObject, r as AgentMessage, s as JsonPrimitive, t as AgentEvent, u as SCHEMA_NOT_TRANSPORTABLE } from "./index-D_RBJmVt.mjs";
+import { ModelGateway, ModelGenerateInput, ModelGenerateResult, ModelRef, ModelUsage, ReasoningEffort } from "./models/index.mjs";
+import { AgentDefinition, AgentLimits, defineAgent } from "./agents/index.mjs";
+import { RunRequest, RunResult } from "./runtime/index.mjs";
+import { ToolDefinition, ToolExecutionContext, ToolResult, defineTool, toToolSpec } from "./tools/index.mjs";
+//#region src/index.d.ts
+interface FevexConfig {
+  models: Record<string, ModelGateway>;
+  agents: AgentDefinition[];
+  tools?: ToolDefinition[];
+  onEvent?: (event: AgentEvent) => void;
+}
+interface Fevex {
+  runAgent<TInput = unknown, TOutput = unknown>(name: string, request: RunRequest<TInput, TOutput>): Promise<RunResult<TOutput>>;
+}
+declare function createFevex(config: FevexConfig): Fevex;
+//#endregion
+export { AgentDefinition, AgentEvent, AgentEventType, AgentLimits, AgentMessage, AgentMessageRole, ExecutionContext, Fevex, FevexConfig, JsonObject, JsonPrimitive, JsonValue, ModelGateway, ModelGenerateInput, ModelGenerateResult, ModelRef, ModelUsage, ReasoningEffort, RunId, RunRequest, RunResult, SCHEMA_NOT_TRANSPORTABLE, ToolCall, ToolDefinition, ToolExecutionContext, ToolResult, ToolSpec, createFevex, defineAgent, defineTool, toToolSpec };

package/dist/index.mjs

@@ -0,0 +1,273 @@
+import { defineTool, toToolSpec } from "./tools/index.mjs";
+import { defineAgent } from "./agents/index.mjs";
+import "./models/index.mjs";
+import "./runtime/index.mjs";
+//#region src/core/index.ts
+const SCHEMA_NOT_TRANSPORTABLE = "SCHEMA_NOT_TRANSPORTABLE";
+//#endregion
+//#region src/index.ts
+const invalidJsonValue = Symbol("invalid-json-value");
+function normalizeJsonValue(value, seen = /* @__PURE__ */ new WeakSet()) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+	if (typeof value === "number") return Number.isFinite(value) ? value : invalidJsonValue;
+	if (Array.isArray(value)) {
+		const normalized = [];
+		for (const item of value) {
+			const normalizedItem = normalizeJsonValue(item, seen);
+			if (normalizedItem === invalidJsonValue) return invalidJsonValue;
+			normalized.push(normalizedItem);
+		}
+		return normalized;
+	}
+	if (typeof value !== "object" || value === void 0) return invalidJsonValue;
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== null && prototype !== Object.prototype) return invalidJsonValue;
+	if (seen.has(value)) return invalidJsonValue;
+	seen.add(value);
+	const normalized = {};
+	for (const [key, item] of Object.entries(value)) {
+		if (item === void 0) continue;
+		const normalizedItem = normalizeJsonValue(item, seen);
+		if (normalizedItem === invalidJsonValue) return invalidJsonValue;
+		normalized[key] = normalizedItem;
+	}
+	seen.delete(value);
+	return normalized;
+}
+function toJsonValue(value, errorMessage) {
+	let normalized;
+	try {
+		normalized = normalizeJsonValue(value);
+	} catch {
+		throw new TypeError(errorMessage);
+	}
+	if (normalized === invalidJsonValue) throw new TypeError(errorMessage);
+	return normalized;
+}
+function serializeJsonValue(value) {
+	return typeof value === "string" ? value : JSON.stringify(value);
+}
+function serializeValue(value, errorMessage) {
+	return serializeJsonValue(toJsonValue(value, errorMessage));
+}
+function isStandardSchema(value) {
+	if (typeof value !== "object" || value === null || !("~standard" in value)) return false;
+	const standard = value["~standard"];
+	return typeof standard === "object" && standard !== null && standard.version === 1 && typeof standard.validate === "function";
+}
+function assertStandardSchema(value, errorMessage) {
+	if (!isStandardSchema(value)) throw new TypeError(errorMessage);
+}
+function isStandardJsonSchema(value) {
+	if (!isStandardSchema(value)) return false;
+	const jsonSchema = value["~standard"].jsonSchema;
+	return typeof jsonSchema === "object" && jsonSchema !== null && typeof jsonSchema.input === "function" && typeof jsonSchema.output === "function";
+}
+function schemaNotTransportable(message) {
+	return Object.assign(new TypeError(message), { code: SCHEMA_NOT_TRANSPORTABLE });
+}
+function toTransportableSchema(schema, direction, errorMessage) {
+	if (!isStandardJsonSchema(schema)) throw schemaNotTransportable(`${errorMessage}: schema does not implement Standard JSON Schema`);
+	let rawSchema;
+	try {
+		rawSchema = schema["~standard"].jsonSchema[direction]({ target: "draft-2020-12" });
+	} catch (error) {
+		throw schemaNotTransportable(`${errorMessage}: ${toErrorMessage(error)}`);
+	}
+	let jsonSchema;
+	try {
+		jsonSchema = toJsonValue(rawSchema, `${errorMessage}: JSON Schema must be JSON-serializable`);
+	} catch {
+		throw schemaNotTransportable(`${errorMessage}: JSON Schema must be JSON-serializable`);
+	}
+	if (typeof jsonSchema !== "object" || jsonSchema === null || Array.isArray(jsonSchema)) throw schemaNotTransportable(`${errorMessage}: JSON Schema must be an object`);
+	return jsonSchema;
+}
+async function validateSchema(schema, value, errorMessage) {
+	const result = await schema["~standard"].validate(value);
+	if (result.issues) {
+		const detail = result.issues[0]?.message ?? "Validation failed";
+		throw new TypeError(`${errorMessage}: ${detail}`);
+	}
+	return result.value;
+}
+function toErrorMessage(error) {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	try {
+		return JSON.stringify(error) ?? String(error);
+	} catch {
+		return String(error);
+	}
+}
+function addUsage(first, second) {
+	if (!first) return second;
+	if (!second) return first;
+	const inputTokens = first.inputTokens === void 0 && second.inputTokens === void 0 ? void 0 : (first.inputTokens ?? 0) + (second.inputTokens ?? 0);
+	const outputTokens = first.outputTokens === void 0 && second.outputTokens === void 0 ? void 0 : (first.outputTokens ?? 0) + (second.outputTokens ?? 0);
+	const totalTokens = first.totalTokens === void 0 && second.totalTokens === void 0 ? void 0 : (first.totalTokens ?? 0) + (second.totalTokens ?? 0);
+	return {
+		...inputTokens !== void 0 ? { inputTokens } : {},
+		...outputTokens !== void 0 ? { outputTokens } : {},
+		...totalTokens !== void 0 ? { totalTokens } : {}
+	};
+}
+function createFevex(config) {
+	const models = new Map(Object.entries(config.models));
+	const agents = /* @__PURE__ */ new Map();
+	const tools = /* @__PURE__ */ new Map();
+	for (const [name, model] of models) {
+		if (!name.trim()) throw new Error("Model name cannot be empty");
+		if (!model || typeof model.generate !== "function") throw new Error(`Model "${name}" must implement generate`);
+	}
+	for (const tool of config.tools ?? []) {
+		if (!tool.name.trim()) throw new Error("Tool name cannot be empty");
+		if (tools.has(tool.name)) throw new Error(`Tool "${tool.name}" is duplicated`);
+		if (tool.inputSchema !== void 0) assertStandardSchema(tool.inputSchema, `Input schema for tool "${tool.name}" must implement Standard Schema`);
+		if (tool.outputSchema !== void 0) assertStandardSchema(tool.outputSchema, `Output schema for tool "${tool.name}" must implement Standard Schema`);
+		tools.set(tool.name, tool);
+	}
+	for (const agent of config.agents) {
+		if (!agent.name.trim()) throw new Error("Agent name cannot be empty");
+		if (!agent.instructions.trim()) throw new Error(`Agent "${agent.name}" instructions cannot be empty`);
+		if (agents.has(agent.name)) throw new Error(`Agent "${agent.name}" is duplicated`);
+		if (agent.outputSchema !== void 0) assertStandardSchema(agent.outputSchema, `Output schema for agent "${agent.name}" must implement Standard Schema`);
+		agents.set(agent.name, agent);
+	}
+	for (const agent of agents.values()) {
+		if (typeof agent.model === "string" && !models.has(agent.model)) throw new Error(`Model "${agent.model}" required by agent "${agent.name}" is not registered`);
+		if (agent.model && typeof agent.model !== "string" && typeof agent.model.generate !== "function") throw new Error(`Model for agent "${agent.name}" must implement generate`);
+		if (!agent.model && !models.has("default")) throw new Error(`Default model "default" required by agent "${agent.name}" is not registered`);
+		for (const toolName of agent.tools ?? []) if (!tools.has(toolName)) throw new Error(`Tool "${toolName}" required by agent "${agent.name}" is not registered`);
+	}
+	return { async runAgent(name, request) {
+		const agent = agents.get(name);
+		if (!agent) throw new Error(`Agent "${name}" is not registered`);
+		const model = typeof agent.model === "string" ? models.get(agent.model) : agent.model ?? models.get("default");
+		const runId = globalThis.crypto.randomUUID();
+		const events = [];
+		const createEvent = (type, payload) => ({
+			type,
+			runId,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			...payload === void 0 ? {} : { payload }
+		});
+		const emit = (type, payload) => {
+			const event = createEvent(type, payload);
+			config.onEvent?.(event);
+			events.push(event);
+		};
+		const emitFailure = (type, payload) => {
+			const event = createEvent(type, payload);
+			try {
+				config.onEvent?.(event);
+			} catch {}
+			events.push(event);
+		};
+		try {
+			emit("run.started");
+			request.signal?.throwIfAborted();
+			if (request.outputSchema !== void 0) assertStandardSchema(request.outputSchema, `Output schema for request to agent "${name}" must implement Standard Schema`);
+			const messages = [{
+				role: "system",
+				content: agent.instructions
+			}, {
+				role: "user",
+				content: serializeValue(request.input, "Run input must be a string or JSON-serializable value")
+			}];
+			const activeOutputSchema = request.outputSchema !== void 0 ? request.outputSchema : agent.outputSchema;
+			const outputSchema = activeOutputSchema === void 0 ? void 0 : toTransportableSchema(activeOutputSchema, "output", `Output schema for agent "${name}" is not transportable`);
+			const agentTools = (agent.tools ?? []).map((toolName) => {
+				const tool = tools.get(toolName);
+				return toToolSpec(tool, tool.inputSchema === void 0 ? void 0 : toTransportableSchema(tool.inputSchema, "input", `Input schema for tool "${tool.name}" is not transportable`));
+			});
+			const result = await model.generate({
+				messages,
+				tools: agentTools.length > 0 ? agentTools : void 0,
+				reasoning: agent.reasoning,
+				modelOptions: agent.modelOptions,
+				outputSchema,
+				signal: request.signal
+			});
+			emit("model.completed");
+			if (!result.toolCalls?.length) {
+				if (result.output === void 0) throw new Error(`Model for agent "${name}" returned no output`);
+				const output = toJsonValue(activeOutputSchema === void 0 ? result.output : await validateSchema(activeOutputSchema, result.output, `Output from agent "${name}" does not match outputSchema`), `Output from agent "${name}" must be JSON-serializable`);
+				emit("run.completed");
+				return {
+					output,
+					events,
+					usage: result.usage
+				};
+			}
+			if (result.toolCalls.length > 1) throw new Error(`Agent "${name}" requested multiple tools, but this runtime supports one tool call`);
+			const toolCall = result.toolCalls[0];
+			if (typeof toolCall.id !== "string" || !toolCall.id.trim()) throw new Error("Tool call id cannot be empty");
+			if (typeof toolCall.name !== "string" || !toolCall.name.trim()) throw new Error("Tool call name cannot be empty");
+			const assistantContent = result.output === void 0 ? "" : serializeValue(result.output, `Model output for agent "${name}" must be JSON-serializable`);
+			request.signal?.throwIfAborted();
+			let toolContent;
+			try {
+				const tool = agent.tools?.includes(toolCall.name) ? tools.get(toolCall.name) : void 0;
+				if (!tool) throw new Error(`Tool "${toolCall.name}" is not available to agent "${name}"`);
+				const rawToolInput = toJsonValue(toolCall.input, `Input for tool "${toolCall.name}" must be JSON-serializable`);
+				const toolInput = toJsonValue(tool.inputSchema === void 0 ? rawToolInput : await validateSchema(tool.inputSchema, rawToolInput, `Input for tool "${toolCall.name}" does not match inputSchema`), `Input for tool "${toolCall.name}" must be JSON-serializable`);
+				const rawToolOutput = await tool.execute(toolInput, {
+					runId,
+					toolCallId: toolCall.id,
+					context: request.context,
+					signal: request.signal
+				});
+				toolContent = serializeJsonValue(toJsonValue(tool.outputSchema === void 0 ? rawToolOutput : await validateSchema(tool.outputSchema, rawToolOutput, `Output from tool "${toolCall.name}" does not match outputSchema`), `Output from tool "${toolCall.name}" must be JSON-serializable`));
+			} catch (error) {
+				emitFailure("tool.failed", {
+					toolCallId: toolCall.id,
+					toolName: toolCall.name,
+					error: toErrorMessage(error)
+				});
+				throw error;
+			}
+			emit("tool.completed", {
+				toolCallId: toolCall.id,
+				toolName: toolCall.name
+			});
+			request.signal?.throwIfAborted();
+			const finalResult = await model.generate({
+				messages: [
+					...messages,
+					{
+						role: "assistant",
+						content: assistantContent,
+						toolCalls: [toolCall]
+					},
+					{
+						role: "tool",
+						name: toolCall.name,
+						toolCallId: toolCall.id,
+						content: toolContent
+					}
+				],
+				tools: void 0,
+				reasoning: agent.reasoning,
+				modelOptions: agent.modelOptions,
+				outputSchema,
+				signal: request.signal
+			});
+			emit("model.completed");
+			if (finalResult.toolCalls?.length) throw new Error(`Agent "${name}" requested another tool, but this runtime supports one tool call`);
+			if (finalResult.output === void 0) throw new Error(`Model for agent "${name}" returned no output`);
+			const output = toJsonValue(activeOutputSchema === void 0 ? finalResult.output : await validateSchema(activeOutputSchema, finalResult.output, `Output from agent "${name}" does not match outputSchema`), `Output from agent "${name}" must be JSON-serializable`);
+			emit("run.completed");
+			return {
+				output,
+				events,
+				usage: addUsage(result.usage, finalResult.usage)
+			};
+		} catch (error) {
+			emitFailure("run.failed", { error: toErrorMessage(error) });
+			throw error;
+		}
+	} };
+}
+//#endregion
+export { SCHEMA_NOT_TRANSPORTABLE, createFevex, defineAgent, defineTool, toToolSpec };

package/dist/models/index.d.mts

@@ -0,0 +1,27 @@
+import { d as ToolCall, f as ToolSpec, o as JsonObject, r as AgentMessage } from "../index-D_RBJmVt.mjs";
+//#region src/models/index.d.ts
+type ReasoningEffort = 'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high';
+interface ModelUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+}
+interface ModelGenerateInput {
+  messages: AgentMessage[];
+  tools?: ToolSpec[];
+  reasoning?: ReasoningEffort;
+  modelOptions?: Record<string, unknown>;
+  outputSchema?: JsonObject;
+  signal?: AbortSignal;
+}
+interface ModelGenerateResult<TOutput = unknown> {
+  output?: TOutput;
+  toolCalls?: ToolCall[];
+  usage?: ModelUsage;
+}
+interface ModelGateway {
+  generate(input: ModelGenerateInput): Promise<ModelGenerateResult>;
+}
+type ModelRef = string | ModelGateway;
+//#endregion
+export { ModelGateway, ModelGenerateInput, ModelGenerateResult, ModelRef, ModelUsage, ReasoningEffort };

package/dist/models/index.mjs

@@ -0,0 +1 @@
+export {};

package/dist/runtime/index.d.mts

@@ -0,0 +1,17 @@
+import { a as ExecutionContext, t as AgentEvent } from "../index-D_RBJmVt.mjs";
+import { ModelUsage } from "../models/index.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/runtime/index.d.ts
+interface RunRequest<TInput = unknown, TOutput = unknown> {
+  input: TInput;
+  context?: ExecutionContext;
+  outputSchema?: StandardSchemaV1<unknown, TOutput>;
+  signal?: AbortSignal;
+}
+interface RunResult<TOutput = unknown> {
+  output: TOutput;
+  events?: AgentEvent[];
+  usage?: ModelUsage;
+}
+//#endregion
+export { RunRequest, RunResult };

package/dist/runtime/index.mjs

@@ -0,0 +1 @@
+export {};

package/dist/testing/index.d.mts

@@ -0,0 +1,16 @@
+import { d as ToolCall } from "../index-D_RBJmVt.mjs";
+import { ModelGateway, ModelGenerateInput, ModelGenerateResult } from "../models/index.mjs";
+//#region src/testing/index.d.ts
+interface FakeModel extends ModelGateway {
+  readonly calls: readonly ModelGenerateInput[];
+}
+declare function fakeModel(...responses: ModelGenerateResult[]): FakeModel;
+interface ModelGatewayContract {
+  output?: unknown;
+  toolCall?: ToolCall;
+  usage?: boolean;
+  error?: Error;
+}
+declare function testModelGateway(model: ModelGateway, contract?: ModelGatewayContract): Promise<void>;
+//#endregion
+export { FakeModel, ModelGatewayContract, fakeModel, testModelGateway };

package/dist/testing/index.mjs

@@ -0,0 +1,76 @@
+//#region src/testing/index.ts
+function fakeModel(...responses) {
+	const calls = [];
+	return {
+		calls,
+		async generate(input) {
+			input.signal?.throwIfAborted();
+			const response = responses[calls.length];
+			calls.push(input);
+			if (!response) throw new Error(`fakeModel has no response for call ${calls.length}`);
+			return response;
+		}
+	};
+}
+const contractOutputSchema = { type: "string" };
+const contractToolInputSchema = {
+	type: "object",
+	properties: { query: { type: "string" } },
+	required: ["query"]
+};
+function assert(condition, message) {
+	if (!condition) throw new TypeError(message);
+}
+async function testModelGateway(model, contract = {}) {
+	const output = contract.output ?? "ok";
+	const toolCall = contract.toolCall ?? {
+		id: "call-1",
+		name: "lookup",
+		input: { query: "value" }
+	};
+	const outputResult = await model.generate({
+		messages: [{
+			role: "user",
+			content: "Return a final answer."
+		}],
+		outputSchema: contractOutputSchema
+	});
+	assert(outputResult.output !== void 0, "ModelGateway must return output for a final answer");
+	assert(outputResult.output === output, "ModelGateway returned an unexpected output");
+	if (contract.usage) assert(outputResult.usage !== void 0, "ModelGateway must return usage when the contract requires it");
+	const toolResult = await model.generate({
+		messages: [{
+			role: "user",
+			content: "Call lookup."
+		}],
+		tools: [{
+			name: "lookup",
+			description: "Look up a value.",
+			inputSchema: contractToolInputSchema
+		}]
+	});
+	assert(toolResult.toolCalls?.length === 1, "ModelGateway must return one tool call");
+	assert(toolResult.toolCalls[0]?.id === toolCall.id, "ModelGateway returned an unexpected tool call id");
+	assert(toolResult.toolCalls[0]?.name === toolCall.name, "ModelGateway returned an unexpected tool name");
+	const controller = new AbortController();
+	controller.abort();
+	await model.generate({
+		messages: [{
+			role: "user",
+			content: "This call is aborted."
+		}],
+		signal: controller.signal
+	}).then(() => {
+		throw new TypeError("ModelGateway must reject aborted calls");
+	}, () => {});
+	if (contract.error) await model.generate({ messages: [{
+		role: "user",
+		content: "Propagate an error."
+	}] }).then(() => {
+		throw new TypeError("ModelGateway must propagate provider errors");
+	}, (error) => {
+		assert(error === contract.error, "ModelGateway must preserve provider error identity");
+	});
+}
+//#endregion
+export { fakeModel, testModelGateway };

package/dist/tools/index.d.mts

@@ -0,0 +1,31 @@
+import { t as ExactDefinition } from "../exact-definition-NHBBFlFR.mjs";
+import { a as ExecutionContext, c as JsonValue, d as ToolCall, f as ToolSpec, l as RunId, o as JsonObject } from "../index-D_RBJmVt.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/tools/index.d.ts
+interface ToolExecutionContext {
+  runId: RunId;
+  toolCallId: string;
+  context?: ExecutionContext;
+  signal?: AbortSignal;
+}
+interface ToolDefinition<TInput = unknown, TOutput = unknown> {
+  name: string;
+  description?: string;
+  inputSchema?: StandardSchemaV1<unknown, TInput>;
+  outputSchema?: StandardSchemaV1<unknown, TOutput>;
+  execute(input: TInput, context: ToolExecutionContext): TOutput | Promise<TOutput>;
+}
+type ToolWithSchemas<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1> = Omit<ToolDefinition<StandardSchemaV1.InferOutput<TInputSchema>, StandardSchemaV1.InferOutput<TOutputSchema>>, 'inputSchema' | 'outputSchema'> & {
+  inputSchema: TInputSchema;
+  outputSchema: TOutputSchema;
+};
+type ToolWithInputSchema<TInputSchema extends StandardSchemaV1> = Omit<ToolDefinition<StandardSchemaV1.InferOutput<TInputSchema>, unknown>, 'inputSchema'> & {
+  inputSchema: TInputSchema;
+};
+declare function defineTool<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TDefinition extends ToolWithSchemas<TInputSchema, TOutputSchema>>(tool: ToolWithSchemas<TInputSchema, TOutputSchema> & ExactDefinition<TDefinition, ToolWithSchemas<TInputSchema, TOutputSchema>>): TDefinition;
+declare function defineTool<TInputSchema extends StandardSchemaV1, TDefinition extends ToolWithInputSchema<TInputSchema>>(tool: ToolWithInputSchema<TInputSchema> & ExactDefinition<TDefinition, ToolWithInputSchema<TInputSchema>>): TDefinition;
+declare function defineTool<TDefinition extends ToolDefinition>(tool: ToolDefinition & ExactDefinition<TDefinition, ToolDefinition>): TDefinition;
+declare function toToolSpec(tool: ToolDefinition, inputSchema?: JsonObject): ToolSpec;
+type ToolResult = JsonValue;
+//#endregion
+export { type ToolCall, ToolDefinition, ToolExecutionContext, ToolResult, type ToolSpec, defineTool, toToolSpec };

package/dist/tools/index.mjs

@@ -0,0 +1,13 @@
+//#region src/tools/index.ts
+function defineTool(tool) {
+	return tool;
+}
+function toToolSpec(tool, inputSchema) {
+	return {
+		name: tool.name,
+		description: tool.description,
+		...inputSchema === void 0 ? {} : { inputSchema }
+	};
+}
+//#endregion
+export { defineTool, toToolSpec };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@fevex/core",
+  "version": "0.1.0-alpha.0",
+  "description": "Agent Engineering Framework for code-first, provider-neutral AI agents.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": ["dist"],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hemia-labs/fevex.git",
+    "directory": "packages/fevex"
+  },
+  "bugs": {
+    "url": "https://github.com/hemia-labs/fevex/issues"
+  },
+  "homepage": "https://github.com/hemia-labs/fevex#readme",
+  "keywords": ["ai", "agents", "agent-framework", "agent-engineering", "typescript", "fevex"],
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./agents": {
+      "types": "./dist/agents/index.d.mts",
+      "import": "./dist/agents/index.mjs"
+    },
+    "./models": {
+      "types": "./dist/models/index.d.mts",
+      "import": "./dist/models/index.mjs"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.mts",
+      "import": "./dist/tools/index.mjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.mts",
+      "import": "./dist/runtime/index.mjs"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.mts",
+      "import": "./dist/testing/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts src/agents/index.ts src/models/index.ts src/tools/index.ts src/runtime/index.ts src/testing/index.ts --format esm --dts",
+    "prepack": "bun run build",
+    "test": "bun test src/index.test.ts src/testing/index.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}