@fevex/core 0.1.0-alpha.1 → 0.1.0-alpha.2

package/dist/testing/index.mjs

@@ -1,28 +1,6 @@
+import { IntegrationError } from "../tools/index.mjs";
 import { t as readModelStream } from "../model-stream-u2xMsEaf.mjs";
-//#region src/testing/index.ts
-function fakeModel(...responses) {
-	const calls = [];
-	return {
-		calls,
-		async *stream(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}`);
-			if (response.output !== void 0) {
-				const delta = typeof response.output === "string" ? response.output : JSON.stringify(response.output);
-				if (delta) yield {
-					type: "output.delta",
-					delta
-				};
-			}
-			yield {
-				type: "completed",
-				result: response
-			};
-		}
-	};
-}
+//#region src/testing/contracts.ts
 const contractOutputSchema = {
 	type: "object",
 	properties: { answer: { type: "string" } },
@@ -38,6 +16,117 @@ const contractToolInputSchema = {
 function assert(condition, message) {
 	if (!condition) throw new TypeError(message);
 }
+async function assertRejects(operation, message, code) {
+	try {
+		await operation();
+	} catch (error) {
+		if (code !== void 0) assert(error instanceof Error && "code" in error && error.code === code, message);
+		return;
+	}
+	throw new TypeError(message);
+}
+async function testMemoryStore(store) {
+	const actor = { id: `actor-${crypto.randomUUID()}` };
+	const sessionId = `session-${crypto.randomUUID()}`;
+	const context = {
+		agentName: "assistant",
+		input: "refund status",
+		sessionId,
+		context: {
+			namespace: "tenant-a",
+			actor
+		}
+	};
+	const saved = await store.write({
+		content: "Refund status is approved.",
+		agentName: "assistant",
+		sessionId,
+		namespace: "tenant-a",
+		actor,
+		metadata: { source: "contract" }
+	}, context);
+	assert(saved.id.trim(), "MemoryRecord id cannot be empty");
+	assert(saved.createdAt.trim(), "MemoryRecord createdAt cannot be empty");
+	saved.content = "mutated";
+	assert((await store.search({
+		query: "refund",
+		sessionId,
+		namespace: "tenant-a",
+		actor
+	}, context))[0]?.content === "Refund status is approved.", "MemoryStore must not expose mutable record references");
+	assert((await store.search({
+		query: "refund",
+		sessionId: "other"
+	}, context)).length === 0, "MemoryStore must isolate sessions");
+	assert((await store.search({
+		query: "refund",
+		namespace: "tenant-b"
+	}, context)).length === 0, "MemoryStore must isolate namespaces");
+	assert((await store.search({
+		query: "refund",
+		actor: { id: "other" }
+	}, context)).length === 0, "MemoryStore must isolate actors");
+	await store.write({
+		content: "Refund backup note.",
+		sessionId,
+		namespace: "tenant-a",
+		actor
+	}, context);
+	assert((await store.search({
+		query: "refund",
+		sessionId,
+		namespace: "tenant-a",
+		actor,
+		limit: 1
+	}, context)).length === 1, "MemoryStore must respect limits");
+	const controller = new AbortController();
+	controller.abort();
+	await store.search({ query: "refund" }, {
+		...context,
+		signal: controller.signal
+	}).then(() => {
+		throw new TypeError("MemoryStore must reject aborted searches");
+	}, () => {});
+}
+async function testToolProvider(provider, contract) {
+	const tools = await provider.listTools({});
+	assert(tools.some((tool) => tool.name === contract.allowedTool), "ToolProvider must list the allowed contract tool");
+	if (contract.disallowedTool !== void 0) assert(!tools.some((tool) => tool.name === contract.disallowedTool), "ToolProvider must not list disallowed tools");
+	const output = await provider.callTool(contract.allowedTool, contract.input ?? { query: "value" }, {});
+	assert(JSON.stringify(output) === JSON.stringify(contract.output ?? { answer: "ok" }), "ToolProvider returned an unexpected output");
+	if (contract.safeError) await Promise.resolve(provider.callTool("contract_error", {}, {})).then(() => {
+		throw new TypeError("ToolProvider must reject configured error calls");
+	}, (error) => {
+		assert(error instanceof IntegrationError, "ToolProvider errors must be IntegrationError");
+		assert(error.message === error.safeMessage, "IntegrationError message must be safe");
+	});
+	if (contract.timeout) {
+		const controller = new AbortController();
+		controller.abort();
+		await Promise.resolve(provider.callTool(contract.allowedTool, {}, { signal: controller.signal })).then(() => {
+			throw new TypeError("ToolProvider must reject aborted calls");
+		}, () => {});
+	}
+}
+async function testChannelAdapter(adapter, contract) {
+	assert(adapter.name.trim(), "ChannelAdapter name cannot be empty");
+	const message = await adapter.parse(contract.input, {});
+	assert(message !== null, "ChannelAdapter must parse the contract input");
+	for (const [name, value] of [
+		["id", message.id],
+		["deliveryId", message.deliveryId],
+		["conversationId", message.conversationId],
+		["content", message.content]
+	]) assert(value.trim(), `ChannelMessage ${name} cannot be empty`);
+	if (message.threadId !== void 0) assert(message.threadId.trim(), "ChannelMessage threadId cannot be empty");
+	if (message.actor !== void 0) assert(message.actor.id.trim(), "ChannelMessage actor id cannot be empty");
+	if (message.metadata !== void 0) JSON.stringify(message.metadata);
+	assert(JSON.stringify(message) === JSON.stringify(contract.message), "ChannelAdapter returned an unexpected message");
+	if (contract.ignoredInput !== void 0) assert(await adapter.parse(contract.ignoredInput, {}) === null, "ChannelAdapter must ignore the configured input");
+	if (contract.output.threadId !== void 0) assert(contract.output.threadId.trim(), "ChannelOutput threadId cannot be empty");
+	if (contract.output.metadata !== void 0) JSON.stringify(contract.output.metadata);
+	assert(JSON.stringify(await adapter.deliver(contract.output, {})) === JSON.stringify(contract.delivered), "ChannelAdapter returned an unexpected delivery");
+}
 async function testModelGateway(model, contract = {}) {
 	const output = contract.output ?? { answer: "ok" };
 	const toolCall = contract.toolCall ?? {
@@ -109,6 +198,126 @@ async function testRunStore(store) {
 	const runId = `contract-run-${suffix}`;
 	const sessionId = `contract-session-${suffix}`;
 	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const atomicRunId = `contract-atomic-run-${suffix}`;
+	const atomicSessionId = `contract-atomic-session-${suffix}`;
+	const atomicRun = {
+		id: atomicRunId,
+		sessionId: atomicSessionId,
+		agentName: "contract-agent",
+		status: "running",
+		revision: 0,
+		createdAt: now,
+		updatedAt: now
+	};
+	const atomicSession = {
+		id: atomicSessionId,
+		history: [],
+		createdAt: now,
+		updatedAt: now
+	};
+	const atomicCheckpoint = {
+		version: 2,
+		runId: atomicRunId,
+		definitionHash: "atomic-definition",
+		messages: [{
+			role: "user",
+			content: "atomic input"
+		}],
+		inputContent: "atomic input",
+		step: 1,
+		toolCallCount: 0,
+		seenToolCallIds: [],
+		pendingTools: [],
+		pendingIndex: 0
+	};
+	const atomicLease = {
+		generation: 0,
+		runId: atomicRunId,
+		ownerId: `atomic-owner-${suffix}`,
+		expiresAt: new Date(Date.now() + 3e4).toISOString()
+	};
+	const atomicStarted = {
+		id: `atomic-event-${suffix}`,
+		sequence: 1,
+		type: "run.started",
+		runId: atomicRunId,
+		timestamp: now
+	};
+	assert(await store.createExecution({
+		run: atomicRun,
+		session: atomicSession,
+		checkpoint: atomicCheckpoint,
+		lease: atomicLease,
+		events: [atomicStarted]
+	}), "RunStore must atomically create a new execution");
+	assert(atomicRun.revision === 1 && (await store.getRun(atomicRunId))?.revision === 1 && (await store.getSession(atomicSessionId))?.id === atomicSessionId && (await store.getCheckpoint(atomicRunId))?.version === 2 && (await store.listEvents(atomicRunId))[0]?.id === atomicStarted.id, "RunStore createExecution must include run, session, checkpoint, lease, and started event");
+	assert(!await store.acquireLease({
+		...atomicLease,
+		ownerId: `atomic-competitor-${suffix}`
+	}), "RunStore createExecution must acquire the initial lease");
+	assert(!await store.createExecution({
+		run: {
+			...atomicRun,
+			revision: 0
+		},
+		session: await store.getSession(atomicRun.sessionId),
+		checkpoint: atomicCheckpoint,
+		lease: atomicLease,
+		events: [atomicStarted]
+	}), "RunStore createExecution must reject duplicate run ids");
+	const ownedSession = await store.getSession(atomicRun.sessionId);
+	const competitorId = `competitor-${suffix}`;
+	const competitor = () => ({
+		run: {
+			...atomicRun,
+			id: competitorId,
+			revision: 0,
+			status: "running"
+		},
+		session: structuredClone(ownedSession),
+		checkpoint: {
+			...atomicCheckpoint,
+			runId: competitorId
+		},
+		lease: {
+			...atomicLease,
+			runId: competitorId
+		},
+		events: []
+	});
+	assert(!await store.createExecution(competitor()), "Active sessions must reject another run");
+	await assertRejects(() => store.saveSession(structuredClone(ownedSession)), "Compaction must reject an active session");
+	assert(await store.commitExecution({
+		lease: atomicLease,
+		expectedRevision: atomicRun.revision,
+		run: Object.assign(atomicRun, { status: "paused" })
+	}), "Owner must be able to pause");
+	await store.releaseLease(atomicRunId, atomicLease.ownerId, atomicLease.generation);
+	assert(!await store.createExecution(competitor()), "Paused sessions remain reserved without a worker lease");
+	await assertRejects(() => store.saveSession(structuredClone(ownedSession)), "Compaction must reject a paused session");
+	assert(await store.acquireLease(atomicLease), "Resume must acquire a new lease generation");
+	assert(await store.commitExecution({
+		lease: atomicLease,
+		expectedRevision: atomicRun.revision,
+		run: Object.assign(atomicRun, { status: "completed" }),
+		session: ownedSession
+	}), "Terminal commit must release the session");
+	const staleSession = structuredClone(ownedSession);
+	await store.saveSession(ownedSession);
+	await assertRejects(() => store.saveSession(staleSession), "Stale compaction must not overwrite history");
+	assert(!await store.createExecution({
+		...competitor(),
+		session: staleSession
+	}), "Run creation must reject history read before compaction");
+	const next = competitor();
+	assert(await store.createExecution(next), "Terminal sessions can be reserved again");
+	assert(!await store.commitExecution({
+		lease: next.lease,
+		expectedRevision: next.run.revision,
+		run: next.run,
+		session: staleSession
+	}), "A stale history commit must fail atomically");
+	assert((await store.getRun(next.run.id))?.revision === next.run.revision, "Rejected history commits must not advance the run");
 	const session = {
 		id: sessionId,
 		history: [],
@@ -126,10 +335,23 @@ async function testRunStore(store) {
 	};
 	await store.saveSession(session);
 	await store.saveRun(run);
+	const commitLease = {
+		generation: 0,
+		runId,
+		ownerId: `writer-${suffix}`,
+		expiresAt: new Date(Date.now() + 3e4).toISOString()
+	};
+	assert(await store.acquireLease(commitLease), "Writer must acquire a lease");
 	const snapshot = await store.getRun(runId);
 	assert(snapshot?.status === "running", "RunStore must return saved runs");
 	snapshot.status = "failed";
 	assert((await store.getRun(runId))?.status === "running", "RunStore must not expose mutable run references");
+	await store.saveRun({
+		...run,
+		status: "completed"
+	});
+	assert((await store.getRun(runId))?.status === "completed", "RunStore must overwrite an existing run on save");
+	await store.saveRun(run);
 	const firstEvent = {
 		id: `event-1-${suffix}`,
 		sequence: 1,
@@ -139,6 +361,7 @@ async function testRunStore(store) {
 	};
 	await store.appendEvent(firstEvent);
 	const checkpoint = {
+		version: 2,
 		runId,
 		definitionHash: "definition",
 		messages: [{
@@ -189,6 +412,7 @@ async function testRunStore(store) {
 		}
 	};
 	assert(await store.commitExecution({
+		lease: commitLease,
 		expectedRevision: 0,
 		run,
 		session,
@@ -199,6 +423,7 @@ async function testRunStore(store) {
 	assert(run.revision === 1, "RunStore must advance the committed run revision");
 	assert((await store.getSession(sessionId))?.history.length === 1 && (await store.getCheckpoint(runId))?.definitionHash === "definition" && (await store.getToolExecution(runId, "tool-call"))?.status === "completed", "RunStore atomic commits must include session, checkpoint, and tool ledger");
 	assert(!await store.commitExecution({
+		lease: commitLease,
 		expectedRevision: 0,
 		run: {
 			...run,
@@ -213,14 +438,64 @@ async function testRunStore(store) {
 			payload: { error: "stale" }
 		}]
 	}), "RunStore must reject stale revisions");
+	const firstPage = await store.listEvents(runId, { limit: 1 });
+	assert(firstPage.length === 1 && firstPage[0]?.id === firstEvent.id, "Event pagination must honor limit and start at the first sequence");
+	assert((await store.listEvents(runId, {
+		after: firstEvent.id,
+		limit: 1
+	}))[0]?.id === secondEvent.id, "Event pagination must continue after the cursor");
+	assert((await store.listEvents(runId, {
+		after: secondEvent.id,
+		limit: 1
+	})).length === 0, "Event pagination after the last event must be empty");
+	const latestPage = await store.listEvents(runId, {
+		order: "desc",
+		limit: 1
+	});
+	assert(latestPage.length === 1 && latestPage[0]?.id === secondEvent.id, "Descending pagination must honor limit and find the latest event");
+	const descending = await store.listEvents(runId, {
+		order: "desc",
+		limit: 2
+	});
+	assert(descending.length === 2 && descending[0]?.id === secondEvent.id && descending[1]?.id === firstEvent.id, "Event pagination must order by sequence");
+	const descendingAfter = await store.listEvents(runId, {
+		after: firstEvent.id,
+		order: "desc",
+		limit: 2
+	});
+	assert(descendingAfter.length === 1 && descendingAfter[0]?.id === secondEvent.id, "Event cursors must select strictly newer sequences even in descending order");
+	await assertRejects(() => store.listEvents(runId, {
+		after: atomicStarted.id,
+		limit: 1
+	}), "Event pagination must reject a cursor from another run with INVALID_CURSOR", "INVALID_CURSOR");
+	for (const limit of [
+		0,
+		-1,
+		NaN,
+		Infinity,
+		1.5
+	]) await assertRejects(() => store.listEvents(runId, { limit }), "Event pagination must validate limits");
 	const events = await store.listEvents(runId, { after: firstEvent.id });
 	assert(events.length === 1 && events[0]?.id === secondEvent.id, "RunStore cursors must return stable ordered suffixes");
+	await assertRejects(() => store.listEvents(`missing-run-${suffix}`), "RunStore listEvents must reject unknown runs");
+	await assertRejects(() => store.listEvents(runId, { after: `missing-cursor-${suffix}` }), "RunStore listEvents must reject unknown cursors with INVALID_CURSOR", "INVALID_CURSOR");
+	assert(await store.commitExecution({
+		lease: commitLease,
+		expectedRevision: 1,
+		run,
+		checkpoint: null
+	}), "RunStore must commit a checkpoint deletion");
+	assert(await store.getCheckpoint(runId) === void 0, "RunStore must delete the checkpoint when a commit sets it to null");
+	assert((await store.getToolExecution(runId, "tool-call"))?.status === "completed", "RunStore must keep the tool ledger when a checkpoint is deleted");
+	await store.releaseLease(runId, commitLease.ownerId, commitLease.generation);
 	const lease1 = {
+		generation: 0,
 		runId,
 		ownerId: `owner-1-${suffix}`,
 		expiresAt: new Date(Date.now() + 3e4).toISOString()
 	};
 	const lease2 = {
+		generation: 0,
 		runId,
 		ownerId: `owner-2-${suffix}`,
 		expiresAt: new Date(Date.now() + 3e4).toISOString()
@@ -229,9 +504,122 @@ async function testRunStore(store) {
 	assert(!await store.acquireLease(lease2), "RunStore must reject a competing lease");
 	assert(!await store.renewLease(lease2), "RunStore must reject renewal by another owner");
 	assert(await store.renewLease(lease1), "RunStore must renew a matching lease");
-	await store.releaseLease(runId, lease1.ownerId);
+	await store.releaseLease(runId, lease1.ownerId, lease1.generation);
 	assert(await store.acquireLease(lease2), "RunStore must release a lease for another owner");
-	await store.releaseLease(runId, lease2.ownerId);
+	await store.releaseLease(runId, lease2.ownerId, lease2.generation);
+	assert(!await store.renewLease(lease1), "RunStore must reject renewal of a released lease");
+	const expiredLease = {
+		generation: 0,
+		runId,
+		ownerId: `owner-3-${suffix}`,
+		expiresAt: (/* @__PURE__ */ new Date(Date.now() - 1e3)).toISOString()
+	};
+	const takeoverLease = {
+		generation: 0,
+		runId,
+		ownerId: `owner-4-${suffix}`,
+		expiresAt: new Date(Date.now() + 3e4).toISOString()
+	};
+	assert(await store.acquireLease(expiredLease), "RunStore must acquire a free lease");
+	const beforeTakeover = await store.getRun(runId);
+	assert(!await store.commitExecution({
+		lease: expiredLease,
+		expectedRevision: beforeTakeover.revision,
+		run: {
+			...beforeTakeover,
+			status: "failed"
+		}
+	}), "An expired lease must not commit even before takeover");
+	assert(!await store.renewLease({
+		...expiredLease,
+		expiresAt: takeoverLease.expiresAt
+	}), "An expired lease cannot be revived by renewal");
+	assert(await store.acquireLease(takeoverLease), "RunStore must let another owner take over an expired lease");
+	await store.releaseLease(runId, takeoverLease.ownerId, takeoverLease.generation);
+	const oldToken = { ...takeoverLease };
+	assert(await store.acquireLease(takeoverLease), "A released owner can acquire a new generation");
+	assert(takeoverLease.generation > oldToken.generation, "Generation must increase even for the same owner");
+	const currentRun = await store.getRun(runId);
+	const currentSession = await store.getSession(sessionId);
+	const currentEvents = await store.listEvents(runId);
+	const currentTool = await store.getToolExecution(runId, "tool-call");
+	assert(currentRun.revision === beforeTakeover.revision, "Takeover must be tested before revision changes");
+	const staleCommit = {
+		lease: oldToken,
+		expectedRevision: currentRun.revision,
+		run: {
+			...currentRun,
+			status: "failed"
+		},
+		session: {
+			...currentSession,
+			history: []
+		},
+		checkpoint,
+		toolExecution: {
+			...toolExecution,
+			output: "stale"
+		},
+		events: [{
+			...firstEvent,
+			id: `stale-owner-${suffix}`,
+			sequence: 3
+		}]
+	};
+	assert(!await store.commitExecution(staleCommit), "A previous generation must not commit with a still-current run revision");
+	assert(!await store.commitExecution({
+		...staleCommit,
+		lease: {
+			...takeoverLease,
+			ownerId: "wrong-owner"
+		}
+	}), "Generation alone must not authorize a commit");
+	assert(!await store.renewLease({
+		...oldToken,
+		expiresAt: takeoverLease.expiresAt
+	}), "A stale generation must not renew a new lease owned by the same owner");
+	await store.releaseLease(runId, oldToken.ownerId, oldToken.generation);
+	assert(await store.renewLease(takeoverLease), "A stale release must not revoke the new generation");
+	assert(JSON.stringify(await store.getRun(runId)) === JSON.stringify(currentRun), "Rejected lease commits must not change the run");
+	assert(JSON.stringify(await store.getSession(sessionId)) === JSON.stringify(currentSession), "Rejected lease commits must not change history");
+	assert(JSON.stringify(await store.listEvents(runId)) === JSON.stringify(currentEvents), "Rejected lease commits must not append events");
+	assert(JSON.stringify(await store.getToolExecution(runId, "tool-call")) === JSON.stringify(currentTool), "Rejected lease commits must not change the tool ledger");
+	assert(await store.getCheckpoint(runId) === void 0, "Rejected lease commits must not create checkpoints");
+	assert(await store.commitExecution({
+		lease: takeoverLease,
+		expectedRevision: currentRun.revision,
+		run: {
+			...currentRun,
+			status: "completed"
+		}
+	}), "The current generation must be able to commit");
+	await store.releaseLease(runId, takeoverLease.ownerId, takeoverLease.generation);
+}
+//#endregion
+//#region src/testing/fake-model.ts
+/** Creates a deterministic model gateway for unit tests. */
+function fakeModel(...responses) {
+	const calls = [];
+	return {
+		calls,
+		async *stream(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}`);
+			if (response.output !== void 0) {
+				const delta = typeof response.output === "string" ? response.output : JSON.stringify(response.output);
+				if (delta) yield {
+					type: "output.delta",
+					delta
+				};
+			}
+			yield {
+				type: "completed",
+				result: response
+			};
+		}
+	};
 }
 //#endregion
-export { fakeModel, testModelGateway, testRunStore };
+export { fakeModel, testChannelAdapter, testMemoryStore, testModelGateway, testRunStore, testToolProvider };

package/dist/tools/index.d.mts

@@ -1,3 +1,3 @@
-import { h as ToolSpec, m as ToolCall } from "../index-C_Zpr13f.mjs";
-import { a as ToolResult, c as defineTool, i as ToolIdempotency, l as toToolSpec, n as ToolDefinition, o as ToolRetryPolicy, r as ToolExecutionContext, s as ToolRisk, t as ToolApproval } from "../index-CZGyhNIQ.mjs";
-export { ToolApproval, type ToolCall, ToolDefinition, ToolExecutionContext, ToolIdempotency, ToolResult, ToolRetryPolicy, ToolRisk, type ToolSpec, defineTool, toToolSpec };
+import { g as ToolSpec, m as ToolCall } from "../types-CuoRx12Q.mjs";
+import { C as toToolSpec, S as defineTool, _ as ToolExecutionContext, a as compileFevexJsonSchema, b as ToolRetryPolicy, c as ConnectionToolPolicy, d as ToolProvider, f as ToolProviderContext, g as ToolDefinition, h as ToolApproval, i as FevexJsonSchemaValidator, l as IntegrationError, m as defineConnection, n as FevexJsonSchemaProfileLimits, o as validateFevexJsonSchemaProfile, p as ToolProviderTool, r as FevexJsonSchemaProfileOptions, s as ConnectionDefinition, t as FEVEX_JSON_SCHEMA_PROFILE_VERSION, u as IntegrationErrorCategory, v as ToolIdempotency, x as ToolRisk, y as ToolResult } from "../index-CqOjvtQ9.mjs";
+export { ConnectionDefinition, ConnectionToolPolicy, FEVEX_JSON_SCHEMA_PROFILE_VERSION, FevexJsonSchemaProfileLimits, FevexJsonSchemaProfileOptions, FevexJsonSchemaValidator, IntegrationError, IntegrationErrorCategory, ToolApproval, type ToolCall, ToolDefinition, ToolExecutionContext, ToolIdempotency, ToolProvider, ToolProviderContext, ToolProviderTool, ToolResult, ToolRetryPolicy, ToolRisk, type ToolSpec, compileFevexJsonSchema, defineConnection, defineTool, toToolSpec, validateFevexJsonSchemaProfile };