@effect-agent/testing 0.1.0-beta.10 → 0.1.0-beta.100

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
+export declare const ResearchDocumentId: Schema.brand<Schema.NonEmptyString, "@effect-agent/testing/docs-researcher/ResearchDocumentId">;
+export type ResearchDocumentId = typeof ResearchDocumentId.Type;
+/** Bounded summary text: the ONLY child-derived text that may cross to the parent. */
+export 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">;
+}>, {}>;
+export 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. */
+export 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>;
+export 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. */
+export 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).
+ */
+export declare const FetchDocument: Tool.Tool<"fetch_document", {
+  readonly parameters: typeof DocumentQuery;
+  readonly success: typeof ResearchDocument;
+  readonly failure: typeof DocumentUnavailable;
+  readonly failureMode: "error";
+}, DocumentLibrary>;
+export 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>;
+}>;
+export declare const docContentToolkitLayer: import("effect/Layer").Layer<Tool.Handler<"fetch_document">, never, never>;
+/** Never allowed outside a child Thread or an unredacted fixture value. */
+export declare const docsDocumentBodySecret = "docs-vault-secret-771";
+/** The corpus document ids in canonical fixture order. */
+export declare const researchCorpusDocumentIds: ReadonlyArray<ResearchDocumentId>;
+/** Deterministic library lookup shared by the scripted MCP content handlers. */
+export declare const researchDocumentLookup: (query: DocumentQuery) => Effect.Effect<ResearchDocument, DocumentUnavailable>;
+/** The full fixture document (body includes the secret marker — child-side only). */
+export declare const researchDocumentFor: (documentId: string) => ResearchDocument;
+/** The distinctive body phrase used by context-isolation assertions. */
+export 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;
+}>, {}>;
+export 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;
+}>, {}>;
+export declare class DocumentSummary extends DocumentSummary_base {}
+/** The summary the scripted child writes after fetching the document. */
+export declare const documentSummaryFor: (documentId: string) => DocumentSummary;
+export declare const encodedDocumentSummary: (documentId: string) => string;
+export 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">;
+}>, {}>;
+export 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;
+}>, {}>;
+export declare class SummaryFinding extends SummaryFinding_base {}
+declare const DocumentSummaryFailed_base: Schema.Class<DocumentSummaryFailed, Schema.TaggedStruct<"DocumentSummaryFailed", {
+  readonly childErrorTag: Schema.NonEmptyString;
+}>, import("effect/Cause").YieldableError>;
+export declare class DocumentSummaryFailed extends DocumentSummaryFailed_base {}
+/** Finite per-invocation bounds (SUB-009): one fetch per child, two children per Run. */
+export declare const documentSummaryPolicy: SubagentPolicy;
+export 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). */
+export declare const mapSummaryChildFailure: (failure: {
+  readonly _tag: string;
+}) => DocumentSummaryFailed;
+/** The exact digest strings the durable declaration AND host registration must share (SUB-023). */
+export declare const docsSummarizerDigestStrings: {
+  readonly agent: string;
+  readonly model: string;
+  readonly tools: string;
+};
+/** Runtime wiring: the immutable delegation plus one explicit child Binding (S2 declaration). */
+export 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">>;
+}>, {}>;
+export 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">;
+}>, {}>;
+export declare class ResearchDigest extends ResearchDigest_base {}
+/** Parent-only transcript markers proving child context isolation (SUB-006/SUB-015). */
+export declare const docsCoordinatorConfidentialMarker = "docs-coordinator-vault-19x";
+export declare const docsMissionConfidentialMarker = "docs-mission-dossier-42f";
+export 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>;
+}>;
+export 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. */
+export declare const researchMissionRequest: ResearchRequest;
+/** The coordinator's expected final digest for the given documents. */
+export declare const expectedResearchDigest: (documentIds?: ReadonlyArray<string>) => ResearchDigest;
+//#endregion
+//#region src/fixtures/docs-researcher/harness.d.ts
+export declare const docsResearcherDeploymentId: string & import("effect/Brand").Brand<"@effect-agent/thread/DeploymentId">;
+export declare const docsResearcherProducerId: string & import("effect/Brand").Brand<"@effect-agent/thread/ProducerId">;
+export declare const docsResearcherPrincipal: string & import("effect/Brand").Brand<"@effect-agent/thread/Principal">;
+/** Redacted, deterministic coordinator definition digests for this fixture version. */
+export declare const docsCoordinatorDigests: DefinitionDigests;
+/** The child registration digests — byte-equal to `docsSummarizerDigestStrings` (SUB-023). */
+export declare const docsSummarizerDigests: DefinitionDigests;
+/** Durable admission options for one docs-researcher Submission on one mission lane. */
+export declare const docsResearcherSubmitOptions: (threadId: ThreadId, idempotencyKey: IdempotencyKey) => DurableSubmitOptions;
+/** The structural submit slice of the coordinator Binding (`DurableAgentRuntime.submit`). */
+export 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. */
+export declare const summarizeCallId: (documentId: string) => string;
+/** The child's own scripted fetch Tool Call identity for one document. */
+export 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.
+ */
+export 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.
+ */
+export 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. */
+export declare const docsMcpRequest: McpConnectionRequest;
+export declare const docsMcpIdentity: McpServerIdentity;
+/** The well-behaved scripted content server. */
+export declare const docsMcpConnectorLayer: Layer.Layer<McpConnector>;
+/** Serves a tool description exceeding `maxToolDescriptionBytes` (SEC-013 bound). */
+export declare const docsMcpOversizedConnectorLayer: Layer.Layer<McpConnector>;
+/** Serves a discovery schema that disagrees with the authored toolkit (drift fails closed). */
+export 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.
+ */
+export declare const assertDiscoveryMatchesAuthoredToolkit: (connection: McpConnection) => Effect.Effect<void, McpToolkitMismatch, never>;
+/** Round-trip guard for encoded discovery values persisted as fixture evidence. */
+export declare const DocsMcpDiscoveryEvidence: Schema.Struct<{
+  readonly serverId: Schema.NonEmptyString;
+  readonly toolCount: Schema.Natural;
+  readonly encodedBytes: Schema.Natural;
+  readonly toolkitSchemaDigest: Schema.String;
+}>;
+//#endregion
+export type { DocsResearcherHarness, DocsResearcherHarnessOptions, DocsResearcherHarnessRequirements };
+//# sourceMappingURL=DocsResearcher.d.mts.map