@effect-agent/testing 0.1.0-beta.9 → 0.1.0-beta.90

package/dist/DocsResearcher.d.mts

@@ -0,0 +1,276 @@
+import { Context, Crypto, Effect, Layer, Schema } from "effect";
+import { Tool, Toolkit } from "effect/unstable/ai";
+import * as Agent from "effect-agent/agent";
+import { ResolvedBinding } from "effect-agent/agent-registration";
+import { DurableSubmitOptions } from "effect-agent/durable-agent-runtime";
+import { ThreadId } from "effect-agent/identifiers";
+import { DefinitionDigests } from "effect-agent/records";
+import * as Subagent from "effect-agent/subagent";
+import { SubagentPolicy } from "effect-agent/subagent";
+import { IdempotencyKey } from "effect-agent/submission-ledger";
+import { RuntimeBinding } from "effect-agent/agent-runtime";
+import { McpConnection, McpConnectionRequest, McpConnector, McpDiscovery, McpServerIdentity, McpToolkitMismatch } from "effect-agent/mcp";
+import { RedactionError, Redactor } from "effect-agent/redaction";
+//#region src/fixtures/docs-researcher/definition.d.ts
+declare const ResearchDocumentId: Schema.brand<Schema.NonEmptyString, "@effect-agent/testing/docs-researcher/ResearchDocumentId">;
+type ResearchDocumentId = typeof ResearchDocumentId.Type;
+/** Bounded summary text: the ONLY child-derived text that may cross to the parent. */
+declare const BoundedSummary: Schema.NonEmptyString;
+declare const DocumentQuery_base: Schema.Class<DocumentQuery, Schema.Struct<{
+  readonly documentId: Schema.brand<Schema.NonEmptyString, "@effect-agent/testing/docs-researcher/ResearchDocumentId">;
+}>, {}>;
+declare class DocumentQuery extends DocumentQuery_base {}
+declare const ResearchDocument_base: Schema.Class<ResearchDocument, Schema.Struct<{
+  readonly documentId: Schema.brand<Schema.NonEmptyString, "@effect-agent/testing/docs-researcher/ResearchDocumentId">;
+  readonly title: Schema.NonEmptyString;
+  readonly body: Schema.NonEmptyString;
+}>, {}>;
+/** One bounded research document as the MCP content server exposes it. */
+declare class ResearchDocument extends ResearchDocument_base {}
+declare const DocumentUnavailable_base: Schema.Class<DocumentUnavailable, Schema.TaggedStruct<"DocumentUnavailable", {
+  readonly documentId: Schema.brand<Schema.NonEmptyString, "@effect-agent/testing/docs-researcher/ResearchDocumentId">;
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class DocumentUnavailable extends DocumentUnavailable_base {}
+declare const DocumentLibrary_base: Context.ServiceClass<DocumentLibrary, "@effect-agent/testing/docs-researcher/DocumentLibrary", {
+  readonly fetch: (query: DocumentQuery) => Effect.Effect<ResearchDocument, DocumentUnavailable>;
+}>;
+/** The content store behind the scripted MCP server. */
+declare class DocumentLibrary extends DocumentLibrary_base {}
+/**
+ * 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).
+ */
+declare const FetchDocument: Tool.Tool<"fetch_document", {
+  readonly parameters: typeof DocumentQuery;
+  readonly success: typeof ResearchDocument;
+  readonly failure: typeof DocumentUnavailable;
+  readonly failureMode: "error";
+}, DocumentLibrary>;
+declare const DocContentToolkit: Toolkit.Toolkit<{
+  readonly fetch_document: Tool.Tool<"fetch_document", {
+    readonly parameters: typeof DocumentQuery;
+    readonly success: typeof ResearchDocument;
+    readonly failure: typeof DocumentUnavailable;
+    readonly failureMode: "error";
+  }, DocumentLibrary>;
+}>;
+declare const docContentToolkitLayer: import("effect/Layer").Layer<Tool.Handler<"fetch_document">, never, never>;
+/** Never allowed outside a child Thread or an unredacted fixture value. */
+declare const docsDocumentBodySecret = "docs-vault-secret-771";
+/** The corpus document ids in canonical fixture order. */
+declare const researchCorpusDocumentIds: ReadonlyArray<ResearchDocumentId>;
+/** Deterministic library lookup shared by the scripted MCP content handlers. */
+declare const researchDocumentLookup: (query: DocumentQuery) => Effect.Effect<ResearchDocument, DocumentUnavailable>;
+/** The full fixture document (body includes the secret marker — child-side only). */
+declare const researchDocumentFor: (documentId: string) => ResearchDocument;
+/** The distinctive body phrase used by context-isolation assertions. */
+declare const documentBodyPhrase: (documentId: string) => string;
+declare const SummaryBrief_base: Schema.Class<SummaryBrief, Schema.Struct<{
+  readonly documentId: Schema.brand<Schema.NonEmptyString, "@effect-agent/testing/docs-researcher/ResearchDocumentId">;
+  readonly focus: Schema.NonEmptyString;
+}>, {}>;
+declare class SummaryBrief extends SummaryBrief_base {}
+declare const DocumentSummary_base: Schema.Class<DocumentSummary, Schema.Struct<{
+  readonly documentId: Schema.brand<Schema.NonEmptyString, "@effect-agent/testing/docs-researcher/ResearchDocumentId">;
+  readonly summary: Schema.NonEmptyString;
+}>, {}>;
+declare class DocumentSummary extends DocumentSummary_base {}
+/** The summary the scripted child writes after fetching the document. */
+declare const documentSummaryFor: (documentId: string) => DocumentSummary;
+declare const encodedDocumentSummary: (documentId: string) => string;
+declare const DocSummarizer: Agent.Definition<typeof SummaryBrief, typeof DocumentSummary, "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.Toolkit<{
+  readonly fetch_document: Tool.Tool<"fetch_document", {
+    readonly parameters: typeof DocumentQuery;
+    readonly success: typeof ResearchDocument;
+    readonly failure: typeof DocumentUnavailable;
+    readonly failureMode: "error";
+  }, DocumentLibrary>;
+}>, undefined, undefined, undefined> & {
+  readonly id: import("effect/Brand").Brand<"@effect-agent/core/AgentId"> & "doc-summarizer";
+};
+declare const SummaryRequest_base: Schema.Class<SummaryRequest, Schema.Struct<{
+  readonly documentId: Schema.brand<Schema.NonEmptyString, "@effect-agent/testing/docs-researcher/ResearchDocumentId">;
+}>, {}>;
+declare class SummaryRequest extends SummaryRequest_base {}
+declare const SummaryFinding_base: Schema.Class<SummaryFinding, Schema.Struct<{
+  readonly documentId: Schema.brand<Schema.NonEmptyString, "@effect-agent/testing/docs-researcher/ResearchDocumentId">;
+  readonly summary: Schema.NonEmptyString;
+}>, {}>;
+declare class SummaryFinding extends SummaryFinding_base {}
+declare const DocumentSummaryFailed_base: Schema.Class<DocumentSummaryFailed, Schema.TaggedStruct<"DocumentSummaryFailed", {
+  readonly childErrorTag: Schema.NonEmptyString;
+}>, import("effect/Cause").YieldableError>;
+declare class DocumentSummaryFailed extends DocumentSummaryFailed_base {}
+/** Finite per-invocation bounds (SUB-009): one fetch per child, two children per Run. */
+declare const documentSummaryPolicy: SubagentPolicy;
+declare const delegateDocumentSummary: Subagent.SubagentDelegation<"delegate_document_summary", typeof SummaryBrief, typeof DocumentSummary, "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.", {
+  readonly fetch_document: Tool.Tool<"fetch_document", {
+    readonly parameters: typeof DocumentQuery;
+    readonly success: typeof ResearchDocument;
+    readonly failure: typeof DocumentUnavailable;
+    readonly failureMode: "error";
+  }, DocumentLibrary>;
+}, typeof SummaryRequest, typeof SummaryFinding, typeof DocumentSummaryFailed, never, never, "error"> & {
+  readonly target: Agent.Definition<typeof SummaryBrief, typeof DocumentSummary, "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.Toolkit<{
+    readonly fetch_document: Tool.Tool<"fetch_document", {
+      readonly parameters: typeof DocumentQuery;
+      readonly success: typeof ResearchDocument;
+      readonly failure: typeof DocumentUnavailable;
+      readonly failureMode: "error";
+    }, DocumentLibrary>;
+  }>, undefined, undefined, undefined> & {
+    readonly id: import("effect/Brand").Brand<"@effect-agent/core/AgentId"> & "doc-summarizer";
+  };
+};
+/** Total mapping from every expected child Run failure to the declared Tool failure (SUB-028). */
+declare const mapSummaryChildFailure: (failure: {
+  readonly _tag: string;
+}) => DocumentSummaryFailed;
+/** The exact digest strings the durable declaration AND host registration must share (SUB-023). */
+declare const docsSummarizerDigestStrings: {
+  readonly agent: string;
+  readonly model: string;
+  readonly tools: string;
+};
+/** Runtime wiring: the immutable delegation plus one explicit child Binding (S2 declaration). */
+declare const docsSummaryHandlersLayer: <Provider, ModelProvides, ModelRequires>(childBinding: RuntimeBinding<typeof SummaryBrief, typeof DocumentSummary, string, Toolkit.Tools<typeof DocContentToolkit>, Provider, ModelProvides, ModelRequires>) => import("effect/Layer").Layer<Tool.Handler<"delegate_document_summary">, never, Subagent.SubagentLayerRequirements<typeof SummaryBrief, typeof DocumentSummary, string, {
+  readonly fetch_document: Tool.Tool<"fetch_document", {
+    readonly parameters: typeof DocumentQuery;
+    readonly success: typeof ResearchDocument;
+    readonly failure: typeof DocumentUnavailable;
+    readonly failureMode: "error";
+  }, DocumentLibrary>;
+}, Provider, ModelProvides, ModelRequires, never, never, never, {
+  readonly _tag: string;
+}, never, undefined, undefined, undefined>>;
+declare const ResearchRequest_base: Schema.Class<ResearchRequest, Schema.Struct<{
+  readonly question: Schema.NonEmptyString;
+  readonly documentIds: Schema.$Array<Schema.brand<Schema.NonEmptyString, "@effect-agent/testing/docs-researcher/ResearchDocumentId">>;
+}>, {}>;
+declare class ResearchRequest extends ResearchRequest_base {}
+declare const ResearchDigest_base: Schema.Class<ResearchDigest, Schema.Struct<{
+  readonly findings: Schema.$Array<typeof SummaryFinding>;
+  readonly nextAction: Schema.Literal<"review">;
+}>, {}>;
+declare class ResearchDigest extends ResearchDigest_base {}
+/** Parent-only transcript markers proving child context isolation (SUB-006/SUB-015). */
+declare const docsCoordinatorConfidentialMarker = "docs-coordinator-vault-19x";
+declare const docsMissionConfidentialMarker = "docs-mission-dossier-42f";
+declare const DocsResearcherToolkit: Toolkit.Toolkit<{
+  readonly delegate_document_summary: Tool.Tool<"delegate_document_summary", {
+    readonly parameters: typeof SummaryRequest;
+    readonly success: typeof SummaryFinding;
+    readonly failure: Subagent.SubagentToolFailure<typeof DocumentSummaryFailed>;
+    readonly failureMode: "error";
+  }, import("effect-agent/agent-runtime").AgentSpawner | import("effect-agent/run-event-sink").RunEventSink | import("effect-agent/agent-runtime").SubagentDurability>;
+}>;
+declare const DocsResearcher: Agent.Definition<typeof ResearchRequest, typeof ResearchDigest, string, Toolkit.Toolkit<{
+  readonly delegate_document_summary: Tool.Tool<"delegate_document_summary", {
+    readonly parameters: typeof SummaryRequest;
+    readonly success: typeof SummaryFinding;
+    readonly failure: Subagent.SubagentToolFailure<typeof DocumentSummaryFailed>;
+    readonly failureMode: "error";
+  }, import("effect-agent/agent-runtime").AgentSpawner | import("effect-agent/run-event-sink").RunEventSink | import("effect-agent/agent-runtime").SubagentDurability>;
+}>, undefined, undefined, undefined> & {
+  readonly id: import("effect/Brand").Brand<"@effect-agent/core/AgentId"> & "docs-researcher";
+};
+/** The default two-document research mission. */
+declare const researchMissionRequest: ResearchRequest;
+/** The coordinator's expected final digest for the given documents. */
+declare const expectedResearchDigest: (documentIds?: ReadonlyArray<string>) => ResearchDigest;
+//#endregion
+//#region src/fixtures/docs-researcher/harness.d.ts
+declare const docsResearcherDeploymentId: string & import("effect/Brand").Brand<"@effect-agent/thread/DeploymentId">;
+declare const docsResearcherProducerId: string & import("effect/Brand").Brand<"@effect-agent/thread/ProducerId">;
+declare const docsResearcherPrincipal: string & import("effect/Brand").Brand<"@effect-agent/thread/Principal">;
+/** Redacted, deterministic coordinator definition digests for this fixture version. */
+declare const docsCoordinatorDigests: DefinitionDigests;
+/** The child registration digests — byte-equal to `docsSummarizerDigestStrings` (SUB-023). */
+declare const docsSummarizerDigests: DefinitionDigests;
+/** Durable admission options for one docs-researcher Submission on one mission lane. */
+declare const docsResearcherSubmitOptions: (threadId: ThreadId, idempotencyKey: IdempotencyKey) => DurableSubmitOptions;
+/** The structural submit slice of the coordinator Binding (`DurableAgentRuntime.submit`). */
+declare const docsResearcherSubmitAgent: {
+  readonly definition: {
+    readonly id: import("effect/Brand").Brand<"@effect-agent/core/AgentId"> & "docs-researcher";
+    readonly input: typeof ResearchRequest;
+  };
+};
+/** The deterministic delegation Tool Call identity for one document. */
+declare const summarizeCallId: (documentId: string) => string;
+/** The child's own scripted fetch Tool Call identity for one document. */
+declare const fetchCallId: (documentId: string) => string;
+/** Optional overrides for one docs-researcher harness. */
+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. */
+interface DocsResearcherHarness {
+  /** Resolved registrations for the parent and child workers. */
+  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.
+ */
+declare const makeDocsResearcherHarness: (options?: DocsResearcherHarnessOptions) => Effect.Effect<DocsResearcherHarness, import("effect-agent/mcp").McpConnectionError | import("effect-agent/mcp").McpDiscoveryLimitExceeded | import("effect-agent/mcp").McpToolkitMismatch, Crypto.Crypto>;
+/**
+ * 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 Thread (SEC-008,
+ * CAP-013). Tests assert the preview keeps shape but no scalar content.
+ */
+declare const redactedDocumentPreview: (documentId: string) => Effect.Effect<string & import("effect/Brand").Brand<"@effect-agent/capabilities/RedactedPreview">, RedactionError, Redactor>;
+type DocsResearcherHarnessRequirements = Crypto.Crypto;
+//#endregion
+//#region src/fixtures/docs-researcher/mcp.d.ts
+/** Framework-side hard bounds one docs-researcher assembly requests. */
+declare const docsMcpRequest: McpConnectionRequest;
+declare const docsMcpIdentity: McpServerIdentity;
+/** The well-behaved scripted content server. */
+declare const docsMcpConnectorLayer: Layer.Layer<McpConnector>;
+/** Serves a tool description exceeding `maxToolDescriptionBytes` (SEC-013 bound). */
+declare const docsMcpOversizedConnectorLayer: Layer.Layer<McpConnector>;
+/** Serves a discovery schema that disagrees with the authored toolkit (drift fails closed). */
+declare const docsMcpMismatchedConnectorLayer: Layer.Layer<McpConnector>;
+/**
+ * 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.
+ */
+declare const assertDiscoveryMatchesAuthoredToolkit: (connection: McpConnection) => Effect.Effect<void, McpToolkitMismatch, never>;
+/** Round-trip guard for encoded discovery values persisted as fixture evidence. */
+declare const DocsMcpDiscoveryEvidence: Schema.Struct<{
+  readonly serverId: Schema.NonEmptyString;
+  readonly toolCount: Schema.Natural;
+  readonly encodedBytes: Schema.Natural;
+  readonly toolkitSchemaDigest: Schema.String;
+}>;
+//#endregion
+export { BoundedSummary, DocContentToolkit, DocSummarizer, DocsMcpDiscoveryEvidence, DocsResearcher, type DocsResearcherHarness, type DocsResearcherHarnessOptions, type DocsResearcherHarnessRequirements, DocsResearcherToolkit, DocumentLibrary, DocumentQuery, DocumentSummary, DocumentSummaryFailed, DocumentUnavailable, FetchDocument, ResearchDigest, ResearchDocument, ResearchDocumentId, ResearchRequest, SummaryBrief, SummaryFinding, SummaryRequest, assertDiscoveryMatchesAuthoredToolkit, delegateDocumentSummary, docContentToolkitLayer, docsCoordinatorConfidentialMarker, docsCoordinatorDigests, docsDocumentBodySecret, docsMcpConnectorLayer, docsMcpIdentity, docsMcpMismatchedConnectorLayer, docsMcpOversizedConnectorLayer, docsMcpRequest, docsMissionConfidentialMarker, docsResearcherDeploymentId, docsResearcherPrincipal, docsResearcherProducerId, docsResearcherSubmitAgent, docsResearcherSubmitOptions, docsSummarizerDigestStrings, docsSummarizerDigests, docsSummaryHandlersLayer, documentBodyPhrase, documentSummaryFor, documentSummaryPolicy, encodedDocumentSummary, expectedResearchDigest, fetchCallId, makeDocsResearcherHarness, mapSummaryChildFailure, redactedDocumentPreview, researchCorpusDocumentIds, researchDocumentFor, researchDocumentLookup, researchMissionRequest, summarizeCallId };
+//# sourceMappingURL=DocsResearcher.d.mts.map