@effect-agent/testing 0.0.1-beta.0

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

@@ -0,0 +1,342 @@
+import { Subagent, SubagentPolicy, SubagentRuntime } from "@effect-agent/capabilities";
+import { Agent, AgentPolicy } from "@effect-agent/core";
+import type { RuntimeBinding } from "@effect-agent/engine";
+import { Context, Effect, Schema } from "effect";
+import { Tool, Toolkit } from "effect/unstable/ai";
+
+// ---------------------------------------------------------------------------
+// Docs Researcher (P7 internal agent #3, plan §6): a coordinator that
+// delegates per-document summarization to a doc-summarizer child through the
+// S2 durable delegation surface, with the child's content tools served —
+// and validated — through the MCP connector against a scripted MCP fixture.
+// The corpus, tools, and both Agent Definitions are deterministic fixtures in
+// the travel-planner style so DN tests (and any later DC assembly) reuse them.
+// ---------------------------------------------------------------------------
+
+export const ResearchDocumentId = Schema.NonEmptyString.check(Schema.isMaxLength(64)).pipe(
+  Schema.brand("@effect-agent/testing/docs-researcher/ResearchDocumentId"),
+);
+export type ResearchDocumentId = typeof ResearchDocumentId.Type;
+
+const BoundedTitle = Schema.NonEmptyString.check(Schema.isMaxLength(120));
+const BoundedBody = Schema.NonEmptyString.check(Schema.isMaxLength(16 * 1024));
+/** Bounded summary text: the ONLY child-derived text that may cross to the parent. */
+export const BoundedSummary = Schema.NonEmptyString.check(Schema.isMaxLength(240));
+
+export class DocumentQuery extends Schema.Class<DocumentQuery>("DocumentQuery")({
+  documentId: ResearchDocumentId,
+}) {}
+
+/** One bounded research document as the MCP content server exposes it. */
+export class ResearchDocument extends Schema.Class<ResearchDocument>("ResearchDocument")({
+  documentId: ResearchDocumentId,
+  title: BoundedTitle,
+  body: BoundedBody,
+}) {}
+
+export class DocumentUnavailable extends Schema.TaggedErrorClass<DocumentUnavailable>()(
+  "DocumentUnavailable",
+  {
+    documentId: ResearchDocumentId,
+    message: Schema.String,
+  },
+) {}
+
+/** The content store behind the scripted MCP server. */
+export class DocumentLibrary extends Context.Service<
+  DocumentLibrary,
+  {
+    readonly fetch: (query: DocumentQuery) => Effect.Effect<ResearchDocument, DocumentUnavailable>;
+  }
+>()("@effect-agent/testing/docs-researcher/DocumentLibrary") {}
+
+/**
+ * The one content tool the doc-summarizer child uses. Its authored JSON
+ * schema is what MCP discovery must serve byte-for-byte: the scripted MCP
+ * fixture derives its discovery entry from `Tool.getJsonSchema(FetchDocument)`
+ * and `validateMcpDiscovery` re-derives and digests both sides (CAP-009).
+ */
+export const FetchDocument = Tool.make("fetch_document", {
+  description: "Fetch one bounded research document by its identifier.",
+  parameters: DocumentQuery,
+  success: ResearchDocument,
+  failure: DocumentUnavailable,
+  failureMode: "error",
+  dependencies: [DocumentLibrary],
+});
+
+export const DocContentToolkit = Toolkit.make(FetchDocument);
+export const docContentToolkitLayer = DocContentToolkit.toLayer({
+  fetch_document: (query) => Effect.flatMap(DocumentLibrary, (library) => library.fetch(query)),
+});
+
+// ---------------------------------------------------------------------------
+// Deterministic corpus. Every body deliberately embeds BOTH a secret marker
+// and a distinctive body phrase: the tests assert that neither ever reaches
+// the parent Conversation, the parent prompts, or a redacted preview — only
+// the bounded summary crosses the delegation boundary (SUB-015, SEC-008).
+// ---------------------------------------------------------------------------
+
+/** Never allowed outside a child Conversation or an unredacted fixture value. */
+export const docsDocumentBodySecret = "docs-vault-secret-771";
+
+const decodeDocumentId = Schema.decodeSync(ResearchDocumentId);
+
+interface CorpusEntry {
+  readonly document: ResearchDocument;
+  readonly bodyPhrase: string;
+  readonly summary: string;
+}
+
+const corpusEntries = new Map<string, CorpusEntry>(
+  [
+    {
+      documentId: "durability-notes",
+      title: "Durability protocol notes",
+      bodyPhrase: "amber-ledger-passage",
+      summary:
+        "Settlement results are recorded exactly once while external side effects stay at-least-once.",
+    },
+    {
+      documentId: "subagent-notes",
+      title: "Subagent join notes",
+      bodyPhrase: "cobalt-join-corridor",
+      summary: "A parent joins only the verified settlement of its own established child.",
+    },
+  ].map((entry) => [
+    entry.documentId,
+    {
+      document: ResearchDocument.make({
+        documentId: decodeDocumentId(entry.documentId),
+        title: entry.title,
+        body: `${entry.bodyPhrase}: internal working notes. ${docsDocumentBodySecret}. ${entry.summary} Raw notes stay inside the child Conversation.`,
+      }),
+      bodyPhrase: entry.bodyPhrase,
+      summary: entry.summary,
+    },
+  ]),
+);
+
+/** The corpus document ids in canonical fixture order. */
+export const researchCorpusDocumentIds: ReadonlyArray<ResearchDocumentId> = [
+  decodeDocumentId("durability-notes"),
+  decodeDocumentId("subagent-notes"),
+];
+
+const requireCorpusEntry = (documentId: string): CorpusEntry => {
+  const entry = corpusEntries.get(documentId);
+  if (entry === undefined) {
+    throw new Error(`No deterministic corpus entry exists for document ${documentId}`);
+  }
+  return entry;
+};
+
+/** Deterministic library lookup shared by the scripted MCP content handlers. */
+export const researchDocumentLookup = (
+  query: DocumentQuery,
+): Effect.Effect<ResearchDocument, DocumentUnavailable> => {
+  const entry = corpusEntries.get(query.documentId);
+  return entry === undefined
+    ? Effect.fail(
+        DocumentUnavailable.make({
+          documentId: query.documentId,
+          message: "No deterministic corpus entry exists for this document.",
+        }),
+      )
+    : Effect.succeed(entry.document);
+};
+
+/** The full fixture document (body includes the secret marker — child-side only). */
+export const researchDocumentFor = (documentId: string): ResearchDocument =>
+  requireCorpusEntry(documentId).document;
+
+/** The distinctive body phrase used by context-isolation assertions. */
+export const documentBodyPhrase = (documentId: string): string =>
+  requireCorpusEntry(documentId).bodyPhrase;
+
+// ---------------------------------------------------------------------------
+// Doc Summarizer: the child Agent Definition. Its toolkit is the authored
+// `DocContentToolkit`; the harness registers its worker Binding only after
+// MCP discovery validates that exact toolkit (mcp.ts).
+// ---------------------------------------------------------------------------
+
+export class SummaryBrief extends Schema.Class<SummaryBrief>("SummaryBrief")({
+  documentId: ResearchDocumentId,
+  focus: Schema.NonEmptyString,
+}) {}
+
+export class DocumentSummary extends Schema.Class<DocumentSummary>("DocumentSummary")({
+  documentId: ResearchDocumentId,
+  summary: BoundedSummary,
+}) {}
+
+/** The summary the scripted child writes after fetching the document. */
+export const documentSummaryFor = (documentId: string): DocumentSummary =>
+  DocumentSummary.make({
+    documentId: requireCorpusEntry(documentId).document.documentId,
+    summary: requireCorpusEntry(documentId).summary,
+  });
+
+export const encodedDocumentSummary = (documentId: string): string =>
+  JSON.stringify(Schema.encodeSync(DocumentSummary)(documentSummaryFor(documentId)));
+
+export const DocSummarizer = Agent.define("doc-summarizer", {
+  input: SummaryBrief,
+  output: DocumentSummary,
+  instructions:
+    "Fetch the briefed document with fetch_document exactly once, then return only a JSON document summary. Never copy raw notes or secrets into the summary.",
+  toolkit: DocContentToolkit,
+  policy: AgentPolicy.make({
+    maxTurns: 2,
+    maxToolCalls: 1,
+    maxDuration: "30 seconds",
+    toolConcurrency: 1,
+  }),
+  description: "Summarize one bounded research document fetched through MCP content tools.",
+  metadata: { deploymentClass: "DN", phase: "P7" },
+});
+
+// ---------------------------------------------------------------------------
+// Delegation Definition: the coordinator sees exactly one Tool with explicit
+// projections and finite bounds. `projectResult` is the declassification
+// boundary (SUB-015): only the bounded summary crosses; the fetched body —
+// secret marker included — stays in the child Conversation.
+// ---------------------------------------------------------------------------
+
+export class SummaryRequest extends Schema.Class<SummaryRequest>("SummaryRequest")({
+  documentId: ResearchDocumentId,
+}) {}
+
+export class SummaryFinding extends Schema.Class<SummaryFinding>("SummaryFinding")({
+  documentId: ResearchDocumentId,
+  summary: BoundedSummary,
+}) {}
+
+export class DocumentSummaryFailed extends Schema.TaggedErrorClass<DocumentSummaryFailed>()(
+  "DocumentSummaryFailed",
+  {
+    childErrorTag: Schema.NonEmptyString,
+  },
+) {}
+
+/** Finite per-invocation bounds (SUB-009): one fetch per child, two children per Run. */
+export const documentSummaryPolicy = SubagentPolicy.make({
+  maxChildren: 2,
+  maxConcurrency: 2,
+  maxTurns: 2,
+  maxToolCalls: 1,
+  maxDuration: "10 seconds",
+});
+
+export const delegateDocumentSummary = Subagent.define("delegate_document_summary", {
+  description:
+    "Summarize one research document through the doc-summarizer child and return a bounded finding.",
+  target: DocSummarizer,
+  parameters: SummaryRequest,
+  success: SummaryFinding,
+  failure: DocumentSummaryFailed,
+  prepareInput: (request) =>
+    Effect.succeed(
+      SummaryBrief.make({
+        documentId: request.documentId,
+        focus: "summarize:durability-claims",
+      }),
+    ),
+  projectResult: (summary) =>
+    Effect.succeed(
+      SummaryFinding.make({
+        documentId: summary.documentId,
+        summary: summary.summary,
+      }),
+    ),
+  policy: documentSummaryPolicy,
+});
+
+/** Total mapping from every expected child Run failure to the declared Tool failure (SUB-028). */
+export const mapSummaryChildFailure = (failure: { readonly _tag: string }): DocumentSummaryFailed =>
+  DocumentSummaryFailed.make({ childErrorTag: failure._tag });
+
+/** The exact digest strings the durable declaration AND host registration must share (SUB-023). */
+export const docsSummarizerDigestStrings = {
+  agent: "50".repeat(32),
+  model: "51".repeat(32),
+  tools: "52".repeat(32),
+} as const;
+
+/** Runtime wiring: the immutable delegation plus one explicit child Binding (S2 declaration). */
+export const docsSummaryHandlersLayer = <Provider, ModelProvides, ModelRequires>(
+  childBinding: RuntimeBinding<
+    typeof SummaryBrief,
+    typeof DocumentSummary,
+    string,
+    Toolkit.Tools<typeof DocContentToolkit>,
+    Provider,
+    ModelProvides,
+    ModelRequires
+  >,
+) =>
+  SubagentRuntime.layer(delegateDocumentSummary, childBinding, {
+    mapChildFailure: mapSummaryChildFailure,
+    durable: { targetDigests: docsSummarizerDigestStrings },
+  });
+
+// ---------------------------------------------------------------------------
+// Docs Researcher: the parent Agent Definition.
+// ---------------------------------------------------------------------------
+
+export class ResearchRequest extends Schema.Class<ResearchRequest>("ResearchRequest")({
+  question: Schema.NonEmptyString,
+  documentIds: Schema.Array(ResearchDocumentId).check(Schema.isMinLength(1)),
+}) {}
+
+export class ResearchDigest extends Schema.Class<ResearchDigest>("ResearchDigest")({
+  findings: Schema.Array(SummaryFinding),
+  nextAction: Schema.Literal("review"),
+}) {}
+
+/** Parent-only transcript markers proving child context isolation (SUB-006/SUB-015). */
+export const docsCoordinatorConfidentialMarker = "docs-coordinator-vault-19x";
+export const docsMissionConfidentialMarker = "docs-mission-dossier-42f";
+
+export const DocsResearcherToolkit = Toolkit.make(delegateDocumentSummary.tool);
+
+export const DocsResearcher = Agent.define("docs-researcher", {
+  input: ResearchRequest,
+  output: ResearchDigest,
+  instructions: [
+    "You are the Effect Agent P7 docs-researcher coordinator.",
+    `Coordinator-only context: ${docsCoordinatorConfidentialMarker}.`,
+    "Call delegate_document_summary once per requested document in one Tool batch.",
+    "Return only a JSON digest built from the delegated findings. This is read-only research.",
+  ].join("\n"),
+  toolkit: DocsResearcherToolkit,
+  policy: AgentPolicy.make({
+    maxTurns: 2,
+    maxToolCalls: 2,
+    maxDuration: "30 seconds",
+    toolConcurrency: 2,
+  }),
+  description: "Coordinate per-document summarization through one declared delegation Tool.",
+  metadata: { deploymentClass: "DN", phase: "P7" },
+});
+
+/** The default two-document research mission. */
+export const researchMissionRequest = ResearchRequest.make({
+  question: `Summarize the durability and subagent notes; keep ${docsMissionConfidentialMarker} inside the coordinator conversation.`,
+  documentIds: researchCorpusDocumentIds,
+});
+
+/** The coordinator's expected final digest for the given documents. */
+export const expectedResearchDigest = (
+  documentIds: ReadonlyArray<string> = researchCorpusDocumentIds,
+): ResearchDigest =>
+  ResearchDigest.make({
+    findings: documentIds.map((documentId) => {
+      const summary = documentSummaryFor(documentId);
+      return SummaryFinding.make({
+        documentId: summary.documentId,
+        summary: summary.summary,
+      });
+    }),
+    nextAction: "review",
+  });

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

@@ -0,0 +1,316 @@
+import {
+  connectMcp,
+  Redactor,
+  SubagentReservationsMemoryLive,
+  type McpDiscovery,
+  type RedactedPreview,
+  type RedactionError,
+} from "@effect-agent/capabilities";
+import { Agent, type ConversationId } from "@effect-agent/core";
+import {
+  DefinitionDigests,
+  DeploymentId,
+  Digest,
+  DurableWorkerBinding,
+  Principal,
+  ProducerId,
+  type DurableSubmitOptions,
+  type IdempotencyKey,
+  type ResolvedBinding,
+} from "@effect-agent/session";
+import { Crypto, Effect, Layer, Ref, Schema, Stream } from "effect";
+import { LanguageModel, Model, type Response } from "effect/unstable/ai";
+
+import { DeterministicIdGeneratorLayer } from "../travel-planner/deterministic-layers.ts";
+import {
+  DocsResearcher,
+  DocSummarizer,
+  DocumentLibrary,
+  docContentToolkitLayer,
+  docsSummaryHandlersLayer,
+  encodedDocumentSummary,
+  expectedResearchDigest,
+  ResearchDigest,
+  ResearchDocument,
+  researchCorpusDocumentIds,
+  researchDocumentFor,
+  researchDocumentLookup,
+} from "./definition.ts";
+import {
+  assertDiscoveryMatchesAuthoredToolkit,
+  docsMcpConnectorLayer,
+  docsMcpRequest,
+} from "./mcp.ts";
+
+// ---------------------------------------------------------------------------
+// DN durable harness for the docs-researcher (P7 plan §6 agent #3), following
+// `makeDurableResearchHarness` conventions: invocation counters and captured
+// prompts live OUTSIDE the Model Layers so they survive Layer rebuilds across
+// Attempts and separate runtime handles over the same SQLite file.
+// ---------------------------------------------------------------------------
+
+export const docsResearcherDeploymentId = Schema.decodeSync(DeploymentId)(
+  "docs-researcher-p7-deployment",
+);
+export const docsResearcherProducerId = Schema.decodeSync(ProducerId)(
+  "docs-researcher-p7-producer",
+);
+export const docsResearcherPrincipal = Schema.decodeSync(Principal)("docs-researcher-p7-principal");
+
+const digestOf = (pair: string) => Schema.decodeSync(Digest)(pair.repeat(32));
+
+/** Redacted, deterministic coordinator definition digests for this fixture version. */
+export const docsCoordinatorDigests = DefinitionDigests.make({
+  agent: digestOf("40"),
+  model: digestOf("41"),
+  tools: digestOf("42"),
+});
+
+/** The child registration digests — byte-equal to `docsSummarizerDigestStrings` (SUB-023). */
+export const docsSummarizerDigests = DefinitionDigests.make({
+  agent: digestOf("50"),
+  model: digestOf("51"),
+  tools: digestOf("52"),
+});
+
+/** Durable admission options for one docs-researcher Submission on one mission lane. */
+export const docsResearcherSubmitOptions = (
+  conversationId: ConversationId,
+  idempotencyKey: IdempotencyKey,
+): DurableSubmitOptions => ({
+  conversationId,
+  principal: docsResearcherPrincipal,
+  idempotencyKey,
+  definitions: docsCoordinatorDigests,
+});
+
+/** The structural submit slice of the coordinator Binding (`DurableAgentRuntime.submit`). */
+export const docsResearcherSubmitAgent = {
+  definition: { id: DocsResearcher.id, input: DocsResearcher.input },
+} as const;
+
+/** The deterministic delegation Tool Call identity for one document. */
+export const summarizeCallId = (documentId: string): string => `summarize-${documentId}`;
+
+/** The child's own scripted fetch Tool Call identity for one document. */
+export const fetchCallId = (documentId: string): string => `fetch-${documentId}`;
+
+const scriptedUsage = { inputTokens: { total: 96 }, outputTokens: { total: 64 } };
+
+const summaryDelegationParts = (
+  documentIds: ReadonlyArray<string>,
+): ReadonlyArray<Response.StreamPartEncoded> => [
+  ...documentIds.map(
+    (documentId): Response.StreamPartEncoded => ({
+      type: "tool-call",
+      id: summarizeCallId(documentId),
+      name: "delegate_document_summary",
+      params: { documentId },
+      providerExecuted: false,
+    }),
+  ),
+  { type: "finish", reason: "tool-calls", usage: scriptedUsage },
+];
+
+const digestParts = (
+  documentIds: ReadonlyArray<string>,
+): ReadonlyArray<Response.StreamPartEncoded> => [
+  { type: "text-start", id: "digest" },
+  {
+    type: "text-delta",
+    id: "digest",
+    delta: JSON.stringify(Schema.encodeSync(ResearchDigest)(expectedResearchDigest(documentIds))),
+  },
+  { type: "text-end", id: "digest" },
+  { type: "finish", reason: "stop", usage: scriptedUsage },
+];
+
+const fetchParts = (documentId: string): ReadonlyArray<Response.StreamPartEncoded> => [
+  {
+    type: "tool-call",
+    id: fetchCallId(documentId),
+    name: "fetch_document",
+    params: { documentId },
+    providerExecuted: false,
+  },
+  { type: "finish", reason: "tool-calls", usage: scriptedUsage },
+];
+
+const summaryParts = (documentId: string): ReadonlyArray<Response.StreamPartEncoded> => [
+  { type: "text-start", id: "document-summary" },
+  { type: "text-delta", id: "document-summary", delta: encodedDocumentSummary(documentId) },
+  { type: "text-end", id: "document-summary" },
+  { type: "finish", reason: "stop", usage: scriptedUsage },
+];
+
+/**
+ * One prompt-aware scripted model with externally observable counters. A DN
+ * Attempt may resume on a fresh Layer build, so responses derive from the
+ * committed history in the prompt — never from an in-Layer turn counter.
+ */
+const makeCountingModel = (
+  name: string,
+  decide: (promptJson: string) => Effect.Effect<ReadonlyArray<Response.StreamPartEncoded>>,
+) =>
+  Effect.gen(function* () {
+    const calls = yield* Ref.make(0);
+    const prompts = yield* Ref.make<ReadonlyArray<string>>([]);
+    const model = Model.make(
+      "scripted",
+      name,
+      Layer.effect(
+        LanguageModel.LanguageModel,
+        LanguageModel.make({
+          generateText: () => Effect.succeed([]),
+          streamText: (request) =>
+            Stream.unwrap(
+              Effect.gen(function* () {
+                yield* Ref.update(calls, (value) => value + 1);
+                const promptJson = JSON.stringify(request.prompt);
+                yield* Ref.update(prompts, (previous) => [...previous, promptJson]);
+                return Stream.fromIterable(yield* decide(promptJson));
+              }),
+            ),
+        }),
+      ),
+    );
+    return { model, calls: Ref.get(calls), prompts: Ref.get(prompts) };
+  });
+
+/** Optional overrides for one docs-researcher harness. */
+export interface DocsResearcherHarnessOptions {
+  /** Documents to research; defaults to the full two-document corpus. */
+  readonly documentIds?: ReadonlyArray<string> | undefined;
+}
+
+/** One durable coordinator/summarizer pair with observable counters and MCP evidence. */
+export interface DocsResearcherHarness {
+  /** Host registrations for `NodeDurableRuntimeOptions.bindings` (parent + child). */
+  readonly bindings: ReadonlyArray<ResolvedBinding>;
+  /** The validated MCP discovery the child toolkit registration was gated on. */
+  readonly discovery: McpDiscovery;
+  /** Total coordinator model invocations across every Attempt and runtime handle. */
+  readonly parentModelCalls: Effect.Effect<number>;
+  /** JSON-encoded coordinator prompts in request order. */
+  readonly parentPrompts: Effect.Effect<ReadonlyArray<string>>;
+  /** Total summarizer model invocations across every Attempt and runtime handle. */
+  readonly childModelCalls: Effect.Effect<number>;
+  /** JSON-encoded summarizer prompts in request order (context-isolation evidence). */
+  readonly childPrompts: Effect.Effect<ReadonlyArray<string>>;
+  /** MCP content-tool handler executions for one document (external side-effect record). */
+  readonly fetchInvocations: (documentId: string) => Effect.Effect<number>;
+}
+
+/**
+ * Build the docs-researcher harness. Order matters and is the point: the
+ * child's content toolkit is only registered as a worker Binding AFTER the
+ * MCP connector's bounded discovery validated the authored toolkit
+ * byte-for-byte (`connectMcp` + `assertDiscoveryMatchesAuthoredToolkit`), so
+ * "the tools the summarizer runs are the tools discovery served" is enforced
+ * at assembly, not assumed. Content-tool execution then flows through the
+ * counting `DocumentLibrary` — the scripted MCP server's content store.
+ */
+export const makeDocsResearcherHarness = (options?: DocsResearcherHarnessOptions) =>
+  Effect.gen(function* () {
+    const documentIds = options?.documentIds ?? researchCorpusDocumentIds;
+
+    // MCP discovery gate (CAP-009): bounded, digest-verified, fail-closed.
+    const discovery = yield* Effect.scoped(
+      Effect.gen(function* () {
+        const connection = yield* connectMcp(docsMcpRequest);
+        yield* assertDiscoveryMatchesAuthoredToolkit(connection);
+        return connection.discovery;
+      }),
+    ).pipe(Effect.provide(docsMcpConnectorLayer));
+
+    const fetchCounts = yield* Ref.make<ReadonlyMap<string, number>>(new Map());
+    const libraryLayer = Layer.succeed(
+      DocumentLibrary,
+      DocumentLibrary.of({
+        fetch: (query) =>
+          Ref.update(fetchCounts, (current) =>
+            new Map(current).set(query.documentId, (current.get(query.documentId) ?? 0) + 1),
+          ).pipe(Effect.andThen(researchDocumentLookup(query))),
+      }),
+    );
+    const childToolkitLayer = docContentToolkitLayer.pipe(Layer.provideMerge(libraryLayer));
+
+    const childModel = yield* makeCountingModel("doc-summarizer-p7", (promptJson) =>
+      Effect.suspend(() => {
+        const documentId = documentIds.find((candidate) => promptJson.includes(candidate));
+        if (documentId === undefined) {
+          return Effect.die(new Error("The summarizer prompt names no corpus document"));
+        }
+        return Effect.succeed(
+          promptJson.includes(fetchCallId(documentId))
+            ? summaryParts(documentId)
+            : fetchParts(documentId),
+        );
+      }),
+    );
+    const childBinding = Agent.withModel(DocSummarizer, childModel.model);
+
+    const firstCallId = summarizeCallId(documentIds[0] ?? "durability-notes");
+    const parentModel = yield* makeCountingModel("docs-researcher-p7", (promptJson) =>
+      Effect.succeed(
+        promptJson.includes(firstCallId)
+          ? digestParts(documentIds)
+          : summaryDelegationParts(documentIds),
+      ),
+    );
+    const parentBinding = Agent.withModel(DocsResearcher, parentModel.model);
+
+    const delegationLayer = docsSummaryHandlersLayer(childBinding).pipe(
+      Layer.provide(
+        Layer.mergeAll(
+          childToolkitLayer,
+          SubagentReservationsMemoryLive,
+          DeterministicIdGeneratorLayer,
+        ),
+      ),
+    );
+
+    const parentResolved: ResolvedBinding = yield* DurableWorkerBinding.make(
+      parentBinding,
+      docsCoordinatorDigests,
+    ).pipe(Effect.provide(delegationLayer));
+    const childResolved: ResolvedBinding = yield* DurableWorkerBinding.make(
+      childBinding,
+      docsSummarizerDigests,
+    ).pipe(Effect.provide(childToolkitLayer));
+
+    const harness: DocsResearcherHarness = {
+      bindings: [parentResolved, childResolved],
+      discovery,
+      parentModelCalls: parentModel.calls,
+      parentPrompts: parentModel.prompts,
+      childModelCalls: childModel.calls,
+      childPrompts: childModel.prompts,
+      fetchInvocations: (documentId) =>
+        Ref.get(fetchCounts).pipe(Effect.map((current) => current.get(documentId) ?? 0)),
+    };
+    return harness;
+  });
+
+const encodeResearchDocument = Schema.encodeEffect(ResearchDocument);
+
+/**
+ * The audit-surface preview of one fetched document: the raw document —
+ * secret marker and all — passes through the configured structural `Redactor`
+ * before anything may quote it outside the child Conversation (SEC-008,
+ * CAP-013). Tests assert the preview keeps shape but no scalar content.
+ */
+export const redactedDocumentPreview = Effect.fn("DocsResearcher.redactedDocumentPreview")(
+  function* (documentId: string): Effect.fn.Return<RedactedPreview, RedactionError, Redactor> {
+    const redactor = yield* Redactor;
+    const encoded = yield* encodeResearchDocument(researchDocumentFor(documentId)).pipe(
+      Effect.orDie,
+    );
+    return yield* redactor.redact(encoded);
+  },
+);
+
+// Crypto is deliberately in the harness requirements (`connectMcp` digests
+// discovery): callers provide a platform Crypto Layer, keeping this fixture
+// platform-neutral.
+export type DocsResearcherHarnessRequirements = Crypto.Crypto;

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

@@ -0,0 +1,34 @@
+// ---------------------------------------------------------------------------
+// Docs Researcher fixture (P7 internal agent #3): S2 durable delegation on DN
+// with MCP-discovered content tools. See definition.ts / mcp.ts / harness.ts.
+//
+// Authoring friction note (WP7 input; real observations from writing this
+// agent):
+//
+// 1. MCP discovery and Agent authoring do not meet in the type system. The
+//    connector's validated Toolkit arrives as `Toolkit.Any`, while
+//    `Agent.define` needs the statically typed toolkit — so the binding
+//    between "what discovery served" and "what the child was authored
+//    against" had to be re-proved by hand (`assertDiscoveryMatchesAuthoredToolkit`
+//    re-deriving `Tool.getJsonSchema` on both sides). A framework helper that
+//    checks a `McpConnection` against a static Toolkit value (or a typed
+//    `connectMcp(request, expectedToolkit)`) would remove a whole class of
+//    look-alike-toolkit mistakes.
+// 2. The durable delegation declaration (`SubagentRuntimeOptions.durable
+//    .targetDigests`) and the host's `DurableWorkerBinding.make(binding,
+//    digests)` registration must agree byte-for-byte, but nothing shares the
+//    value: the fixture exports both a string form and a decoded
+//    `DefinitionDigests` form of the same digests to keep them from drifting.
+//    One authoritative exported value consumed by both sides would be better.
+// 3. Prompt-aware scripted models are boilerplate-heavy: every durable fixture
+//    (S2 travel planner, P6 planner, this one) re-implements "counters outside
+//    the Layer + decide-from-prompt". A shared `makePromptAwareCountingModel`
+//    in the testing package is an easy WP7 simplification.
+// 4. The delegation surface itself (Subagent.define + projections + policy)
+//    was pleasant to author a second time — bounds and declassification live
+//    exactly where a reviewer looks for them.
+// ---------------------------------------------------------------------------
+
+export * from "./definition.ts";
+export * from "./harness.ts";
+export * from "./mcp.ts";