@effect-agent/testing 0.0.1-beta.0

package/src/fixtures/docs-researcher/mcp.ts

@@ -0,0 +1,126 @@
+import {
+  McpConnectionRequest,
+  McpConnector,
+  McpServerIdentity,
+  McpToolkitMismatch,
+  type McpConnection,
+} from "@effect-agent/capabilities";
+import { Effect, Layer, Schema } from "effect";
+import { Tool } from "effect/unstable/ai";
+import * as McpSchema from "effect/unstable/ai/McpSchema";
+
+import { DocContentToolkit, FetchDocument } from "./definition.ts";
+
+// ---------------------------------------------------------------------------
+// Scripted MCP fixture: a deterministic `McpConnector` adapter that serves the
+// doc-summarizer's content tool. Discovery entries are DERIVED from the
+// authored Tool (`Tool.getJsonSchema`), so `validateMcpDiscovery` digesting
+// both sides is a real check, not a tautology; the mismatch and over-limit
+// connectors below serve deliberately wrong contracts so tests can pin the
+// fail-closed paths (CAP-009, SEC-013).
+// ---------------------------------------------------------------------------
+
+/** Framework-side hard bounds one docs-researcher assembly requests. */
+export const docsMcpRequest = McpConnectionRequest.make({
+  serverId: "docs-content-mcp",
+  maxToolCount: 4,
+  maxToolDescriptionBytes: 256,
+  maxDiscoveryBytes: 16_384,
+  connectTimeoutMillis: 1_000,
+});
+
+export const docsMcpIdentity = McpServerIdentity.make({
+  serverId: docsMcpRequest.serverId,
+  implementation: McpSchema.Implementation.make({
+    name: "docs-researcher-content-fixture",
+    version: "1.0.0",
+  }),
+});
+
+const discoveredFetchDocument = McpSchema.Tool.make({
+  name: FetchDocument.name,
+  description: "Fetch one bounded research document by its identifier.",
+  inputSchema: Tool.getJsonSchema(FetchDocument),
+});
+
+const scriptedConnector = (tools: ReadonlyArray<McpSchema.Tool>): Layer.Layer<McpConnector> =>
+  Layer.succeed(McpConnector)({
+    connect: () =>
+      Effect.acquireRelease(
+        Effect.succeed({
+          identity: docsMcpIdentity,
+          capabilities: McpSchema.ServerCapabilities.make({}),
+          tools,
+          toolkit: DocContentToolkit,
+        }),
+        () => Effect.void,
+      ),
+  });
+
+/** The well-behaved scripted content server. */
+export const docsMcpConnectorLayer: Layer.Layer<McpConnector> = scriptedConnector([
+  discoveredFetchDocument,
+]);
+
+/** Serves a tool description exceeding `maxToolDescriptionBytes` (SEC-013 bound). */
+export const docsMcpOversizedConnectorLayer: Layer.Layer<McpConnector> = scriptedConnector([
+  McpSchema.Tool.make({
+    name: discoveredFetchDocument.name,
+    description: "x".repeat(1_024),
+    inputSchema: discoveredFetchDocument.inputSchema,
+  }),
+]);
+
+/** Serves a discovery schema that disagrees with the authored toolkit (drift fails closed). */
+export const docsMcpMismatchedConnectorLayer: Layer.Layer<McpConnector> = scriptedConnector([
+  McpSchema.Tool.make({
+    name: discoveredFetchDocument.name,
+    description: discoveredFetchDocument.description,
+    inputSchema: { type: "object", properties: { url: { type: "string" } } },
+  }),
+]);
+
+const isJsonEqual = (left: unknown, right: unknown): boolean =>
+  JSON.stringify(left) === JSON.stringify(right);
+
+/**
+ * Bind DISCOVERY to AUTHORING: `validateMcpDiscovery` (inside `connectMcp`)
+ * already proved the served discovery matches the connection's own Toolkit;
+ * this check additionally proves that Toolkit is the exact toolkit the
+ * doc-summarizer was AUTHORED against — same tool names, same derived JSON
+ * schemas — so a connector cannot substitute a look-alike toolkit. The
+ * docs-researcher harness runs it before any worker Binding registration and
+ * fails closed on any drift.
+ */
+export const assertDiscoveryMatchesAuthoredToolkit = Effect.fn(
+  "DocsResearcher.assertDiscoveryMatchesAuthoredToolkit",
+)(function* (connection: McpConnection): Effect.fn.Return<void, McpToolkitMismatch> {
+  const authored = Object.values(DocContentToolkit.tools)
+    .map((tool) => ({ name: tool.name, inputSchema: Tool.getJsonSchema(tool) }))
+    .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+  const discovered = Object.values(connection.toolkit.tools)
+    .map((tool) => ({ name: tool.name, inputSchema: Tool.getJsonSchema(tool) }))
+    .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+  const matches =
+    authored.length === discovered.length &&
+    authored.every(
+      (tool, index) =>
+        tool.name === discovered[index]?.name &&
+        isJsonEqual(tool.inputSchema, discovered[index]?.inputSchema),
+    );
+  if (!matches) {
+    return yield* McpToolkitMismatch.make({
+      serverId: connection.discovery.identity.serverId,
+      message:
+        "The MCP-discovered toolkit does not match the doc-summarizer's authored content toolkit",
+    });
+  }
+});
+
+/** Round-trip guard for encoded discovery values persisted as fixture evidence. */
+export const DocsMcpDiscoveryEvidence = Schema.Struct({
+  serverId: Schema.NonEmptyString,
+  toolCount: Schema.Natural,
+  encodedBytes: Schema.Natural,
+  toolkitSchemaDigest: Schema.String,
+});

package/src/fixtures/travel-planner/definition.ts

@@ -0,0 +1,167 @@
+import { Agent, AgentPolicy } from "@effect-agent/core";
+import { Context, Effect, Schema } from "effect";
+import { Tool, Toolkit } from "effect/unstable/ai";
+
+export const AirportCode = Schema.NonEmptyString.pipe(
+  Schema.brand("@effect-agent/testing/travel-planner/AirportCode"),
+);
+export type AirportCode = typeof AirportCode.Type;
+
+export const QuoteId = Schema.NonEmptyString.pipe(
+  Schema.brand("@effect-agent/testing/travel-planner/QuoteId"),
+);
+export type QuoteId = typeof QuoteId.Type;
+
+export class TripRequest extends Schema.Class<TripRequest>("TripRequest")({
+  request: Schema.NonEmptyString,
+  origin: AirportCode,
+  destination: AirportCode,
+  departOn: Schema.String,
+  nights: Schema.Int.check(Schema.isGreaterThan(0)),
+  travelers: Schema.Int.check(Schema.isGreaterThan(0)),
+  budgetCents: Schema.Int.check(Schema.isGreaterThan(0)),
+  currency: Schema.Literal("USD"),
+}) {}
+
+export class FlightQuery extends Schema.Class<FlightQuery>("FlightQuery")({
+  origin: AirportCode,
+  destination: AirportCode,
+  departOn: Schema.String,
+  travelers: Schema.Int.check(Schema.isGreaterThan(0)),
+}) {}
+
+export class LodgingQuery extends Schema.Class<LodgingQuery>("LodgingQuery")({
+  destination: AirportCode,
+  departOn: Schema.String,
+  nights: Schema.Int.check(Schema.isGreaterThan(0)),
+  travelers: Schema.Int.check(Schema.isGreaterThan(0)),
+}) {}
+
+export class ActivityQuery extends Schema.Class<ActivityQuery>("ActivityQuery")({
+  destination: AirportCode,
+  departOn: Schema.String,
+  nights: Schema.Int.check(Schema.isGreaterThan(0)),
+  travelers: Schema.Int.check(Schema.isGreaterThan(0)),
+}) {}
+
+export class FlightOption extends Schema.Class<FlightOption>("FlightOption")({
+  quoteId: QuoteId,
+  flight: Schema.String,
+  estimatedCents: Schema.Int.check(Schema.isGreaterThan(0)),
+  currency: Schema.Literal("USD"),
+}) {}
+
+export class LodgingOption extends Schema.Class<LodgingOption>("LodgingOption")({
+  lodging: Schema.String,
+  estimatedCents: Schema.Int.check(Schema.isGreaterThan(0)),
+  currency: Schema.Literal("USD"),
+}) {}
+
+/** A successful empty activity search is distinct from supplier unavailability. */
+export class ActivitySearchResult extends Schema.Class<ActivitySearchResult>(
+  "ActivitySearchResult",
+)({
+  activities: Schema.Array(Schema.String),
+}) {}
+
+export class Itinerary extends Schema.Class<Itinerary>("Itinerary")({
+  title: Schema.String,
+  route: Schema.String,
+  dates: Schema.String,
+  flight: Schema.String,
+  lodging: Schema.String,
+  activities: Schema.Array(Schema.String),
+  estimatedTotalCents: Schema.Int.check(Schema.isGreaterThan(0)),
+  currency: Schema.Literal("USD"),
+  quoteId: QuoteId,
+  assumptions: Schema.Array(Schema.String),
+  unresolvedConstraints: Schema.Array(Schema.String),
+  nextAction: Schema.Literal("review"),
+}) {}
+
+export class TravelPlan extends Schema.Class<TravelPlan>("TravelPlan")({
+  itineraries: Schema.Array(Itinerary),
+}) {}
+
+const unavailableFields = { query: Schema.String, message: Schema.String };
+export class FlightUnavailable extends Schema.TaggedErrorClass<FlightUnavailable>()(
+  "FlightUnavailable",
+  unavailableFields,
+) {}
+export class LodgingUnavailable extends Schema.TaggedErrorClass<LodgingUnavailable>()(
+  "LodgingUnavailable",
+  unavailableFields,
+) {}
+export class ActivityUnavailable extends Schema.TaggedErrorClass<ActivityUnavailable>()(
+  "ActivityUnavailable",
+  unavailableFields,
+) {}
+export class GuidanceFailure extends Schema.TaggedErrorClass<GuidanceFailure>()("GuidanceFailure", {
+  message: Schema.String,
+}) {}
+
+export class FlightCatalog extends Context.Service<
+  FlightCatalog,
+  { readonly search: (query: FlightQuery) => Effect.Effect<FlightOption, FlightUnavailable> }
+>()("@effect-agent/testing/travel-planner/FlightCatalog") {}
+export class LodgingCatalog extends Context.Service<
+  LodgingCatalog,
+  { readonly search: (query: LodgingQuery) => Effect.Effect<LodgingOption, LodgingUnavailable> }
+>()("@effect-agent/testing/travel-planner/LodgingCatalog") {}
+export class ActivityCatalog extends Context.Service<
+  ActivityCatalog,
+  {
+    readonly search: (
+      query: ActivityQuery,
+    ) => Effect.Effect<ActivitySearchResult, ActivityUnavailable>;
+  }
+>()("@effect-agent/testing/travel-planner/ActivityCatalog") {}
+export class TravelGuidance extends Context.Service<
+  TravelGuidance,
+  { readonly instructions: (input: TripRequest) => Effect.Effect<string, GuidanceFailure> }
+>()("@effect-agent/testing/travel-planner/TravelGuidance") {}
+
+export const SearchFlights = Tool.make("search_flights", {
+  parameters: FlightQuery,
+  success: FlightOption,
+  failure: FlightUnavailable,
+  failureMode: "error",
+  dependencies: [FlightCatalog],
+});
+export const SearchLodging = Tool.make("search_lodging", {
+  parameters: LodgingQuery,
+  success: LodgingOption,
+  failure: LodgingUnavailable,
+  failureMode: "error",
+  dependencies: [LodgingCatalog],
+});
+export const SearchActivities = Tool.make("search_activities", {
+  parameters: ActivityQuery,
+  success: ActivitySearchResult,
+  failure: ActivityUnavailable,
+  failureMode: "error",
+  dependencies: [ActivityCatalog],
+});
+
+export const TravelPlannerToolkit = Toolkit.make(SearchFlights, SearchLodging, SearchActivities);
+export const TravelPlannerToolkitLayer = TravelPlannerToolkit.toLayer({
+  search_flights: (query) => Effect.flatMap(FlightCatalog, (catalog) => catalog.search(query)),
+  search_lodging: (query) => Effect.flatMap(LodgingCatalog, (catalog) => catalog.search(query)),
+  search_activities: (query) => Effect.flatMap(ActivityCatalog, (catalog) => catalog.search(query)),
+});
+
+export const TravelPlanner = Agent.define("travel-planner", {
+  input: TripRequest,
+  output: TravelPlan,
+  instructions: (input) =>
+    Effect.flatMap(TravelGuidance, (guidance) => guidance.instructions(input)),
+  toolkit: TravelPlannerToolkit,
+  policy: AgentPolicy.make({
+    maxTurns: 2,
+    maxToolCalls: 3,
+    maxDuration: "30 seconds",
+    toolConcurrency: 3,
+  }),
+  description: "Build one review-only itinerary from bounded parallel deterministic searches.",
+  metadata: { deploymentClass: "E", phase: "P1" },
+});