effect-agent 0.1.0-beta.85 → 0.1.0-beta.87

package/dist/capabilities/ToolDiscovery.d.mts

@@ -0,0 +1,109 @@
+import { n as CurrentToolCatalog } from "../ToolExposure-UCN12eCd.mjs";
+import { Tool, Toolkit } from "effect/unstable/ai";
+import { Effect, Schema, Scope } from "effect";
+declare namespace ToolDiscovery_d_exports {
+  export { Descriptor, Match, Options, Parameters, Result, ToolDiscoveryError, make };
+}
+/** Search text is bounded and literal; namespace selects one exact host-declared group. */
+declare const Parameters: Schema.Struct<{
+  readonly query: Schema.NonEmptyString;
+  readonly namespace: Schema.optionalKey<Schema.NonEmptyString>;
+}>;
+declare const Descriptor_base: Schema.Class<Descriptor, Schema.Struct<{
+  readonly id: Schema.NonEmptyString;
+  readonly kind: Schema.Literals<readonly ["native", "code-mode"]>;
+  readonly name: Schema.NonEmptyString;
+  readonly nativeToolName: Schema.NonEmptyString;
+  readonly namespace: Schema.optionalKey<Schema.NonEmptyString>;
+  readonly method: Schema.optionalKey<Schema.NonEmptyString>;
+  readonly description: Schema.optionalKey<Schema.String>;
+  readonly namespaceDescription: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/** Metadata given to custom search only after host visibility and inherited grants are applied. */
+declare class Descriptor extends Descriptor_base {}
+declare const Match_base: Schema.Class<Match, Schema.Struct<{
+  readonly id: Schema.NonEmptyString;
+  readonly kind: Schema.Literals<readonly ["native", "code-mode"]>;
+  readonly name: Schema.NonEmptyString;
+  readonly nativeToolName: Schema.NonEmptyString;
+  readonly namespace: Schema.optionalKey<Schema.NonEmptyString>;
+  readonly method: Schema.optionalKey<Schema.NonEmptyString>;
+  readonly description: Schema.optionalKey<Schema.String>;
+  readonly namespaceDescription: Schema.optionalKey<Schema.String>;
+  readonly parameters: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+  readonly success: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, {}>;
+/**
+ * Selected metadata and canonical encoded Tool Schemas. Provider-specific model schema
+ * transformations do not change the wire values documented for application handlers.
+ */
+declare class Match extends Match_base {}
+/** Only nativeToolName values activate schemas; Code Mode aliases activate their owning Tool. */
+declare const Result: Schema.Struct<{
+  readonly toolNames: Schema.$Array<Schema.NonEmptyString>;
+  readonly matches: Schema.$Array<typeof Match>;
+}>;
+declare const ToolDiscoveryError_base: Schema.Class<ToolDiscoveryError, Schema.TaggedStruct<"ToolDiscoveryError", {
+  readonly reason: Schema.Literals<readonly ["invalid-catalogue", "invalid-matches", "unknown-match", "invalid-schema", "limit-exceeded"]>;
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Invalid custom results, unsupported documentation, and bounded output failures remain typed. */
+declare class ToolDiscoveryError extends ToolDiscoveryError_base {}
+interface Options<Failure extends Schema.Top = typeof Schema.Never, Requirements = never> {
+  /** Optional generic instructions. Namespace names and hints are never appended here. */
+  readonly description?: string | undefined;
+  /** Maximum returned catalogue entries, default 8 and at most 64. */
+  readonly maxResults?: number | undefined;
+  /** Complete JSON-encoded result budget, default 32768 and at most 262144 UTF-8 bytes. */
+  readonly maxResultBytes?: number | undefined;
+  /** Short category hints returned only for namespaces present in the visible catalogue. */
+  readonly namespaceDescriptions?: Readonly<Record<string, string>> | undefined;
+  /** Schema of the custom search's expected failures; defaults to Schema.Never. */
+  readonly failure?: Failure | undefined;
+  /**
+   * Rank unique Descriptor.id values, never tool names. Native tools and each Code Mode alias
+   * have distinct identities. Every returned id is checked before the result limit is applied.
+   * The catalogue is already filtered by the optional exact namespace and current authority.
+   * Services are captured with the handler Layer; temporary resources close after each search.
+   */
+  readonly search?: ((request: typeof Parameters.Type, catalogue: ReadonlyArray<Descriptor>) => Effect.Effect<ReadonlyArray<string>, Failure["Type"], Requirements>) | undefined;
+}
+/**
+ * Build one native discover_tools Tool and its singleton Toolkit/handler Layer. Include the
+ * Tool beside the application's existing native Tools. The engine owns catalogue authority
+ * and applies successful native selections after a complete Tool batch; the handler mutates
+ * no exposure state. Default search matches all case-insensitive whitespace-separated terms
+ * against names, descriptions, methods and namespace hints, ordered by catalogue id.
+ */
+declare const make: <Failure extends Schema.Top = typeof Schema.Never, Requirements = never>(options?: Options<Failure, Requirements>) => Readonly<{
+  tool: Tool.Tool<"discover_tools", {
+    readonly parameters: Schema.Struct<{
+      readonly query: Schema.NonEmptyString;
+      readonly namespace: Schema.optionalKey<Schema.NonEmptyString>;
+    }>;
+    readonly success: Schema.Struct<{
+      readonly toolNames: Schema.$Array<Schema.NonEmptyString>;
+      readonly matches: Schema.$Array<typeof Match>;
+    }>;
+    readonly failure: Schema.Union<readonly [Schema.Codec<Failure["Type"], Failure["Encoded"], Failure["DecodingServices"], Failure["EncodingServices"]>, typeof ToolDiscoveryError]>;
+    readonly failureMode: "error";
+  }, CurrentToolCatalog>;
+  toolkit: Toolkit.Toolkit<{
+    readonly discover_tools: Tool.Tool<"discover_tools", {
+      readonly parameters: Schema.Struct<{
+        readonly query: Schema.NonEmptyString;
+        readonly namespace: Schema.optionalKey<Schema.NonEmptyString>;
+      }>;
+      readonly success: Schema.Struct<{
+        readonly toolNames: Schema.$Array<Schema.NonEmptyString>;
+        readonly matches: Schema.$Array<typeof Match>;
+      }>;
+      readonly failure: Schema.Union<readonly [Schema.Codec<Failure["Type"], Failure["Encoded"], Failure["DecodingServices"], Failure["EncodingServices"]>, typeof ToolDiscoveryError]>;
+      readonly failureMode: "error";
+    }, CurrentToolCatalog>;
+  }>;
+  handlers: import("effect/Layer").Layer<Tool.Handler<"discover_tools">, never, Exclude<Exclude<Requirements, Scope.Scope>, Scope.Scope>>;
+}>;
+//#endregion
+export { Descriptor, Match, Options, Parameters, Result, ToolDiscoveryError, make, ToolDiscovery_d_exports as t };
+//# sourceMappingURL=ToolDiscovery.d.mts.map

package/dist/capabilities/ToolDiscovery.mjs

@@ -0,0 +1,211 @@
+import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
+import { n as utf8ByteLength } from "../utf8-DchGZRBd.mjs";
+import { a as PinnedTool, n as DiscoveryTool } from "../ToolExposure-C93U1sPu.mjs";
+import { t as CurrentToolCatalog } from "../ToolExposure-9uF_Yo0T.mjs";
+import { ToolExecutionClass } from "../engine/DurableStep.mjs";
+import { Tool, Toolkit } from "effect/unstable/ai";
+import { Effect, Schema } from "effect";
+//#region src/capabilities/ToolDiscovery.ts
+var ToolDiscovery_exports = /* @__PURE__ */ __exportAll({
+	Descriptor: () => Descriptor,
+	Match: () => Match,
+	Parameters: () => Parameters,
+	Result: () => Result,
+	ToolDiscoveryError: () => ToolDiscoveryError,
+	make: () => make
+});
+const Name = Schema.NonEmptyString.check(Schema.isMaxLength(256));
+const Namespace = Schema.NonEmptyString.check(Schema.isMaxLength(128));
+const Description = Schema.String.check(Schema.isMaxLength(2048));
+const NamespaceDescription = Schema.String.check(Schema.isMaxLength(512));
+const EntryId = Schema.NonEmptyString.check(Schema.isMaxLength(1024));
+/** Search text is bounded and literal; namespace selects one exact host-declared group. */
+const Parameters = Schema.Struct({
+	query: Schema.NonEmptyString.check(Schema.isMaxLength(512), Schema.isPattern(/\S/)),
+	namespace: Schema.optionalKey(Namespace)
+});
+/** Metadata given to custom search only after host visibility and inherited grants are applied. */
+var Descriptor = class extends Schema.Class("@effect-agent/capabilities/ToolDiscovery/Descriptor")({
+	id: EntryId,
+	kind: Schema.Literals(["native", "code-mode"]),
+	name: Name,
+	nativeToolName: Name,
+	namespace: Schema.optionalKey(Namespace),
+	method: Schema.optionalKey(Schema.NonEmptyString.check(Schema.isMaxLength(128))),
+	description: Schema.optionalKey(Description),
+	namespaceDescription: Schema.optionalKey(NamespaceDescription)
+}) {};
+/**
+* Selected metadata and canonical encoded Tool Schemas. Provider-specific model schema
+* transformations do not change the wire values documented for application handlers.
+*/
+var Match = class extends Schema.Class("@effect-agent/capabilities/ToolDiscovery/Match")({
+	...Descriptor.fields,
+	parameters: Schema.Json,
+	success: Schema.Json
+}) {};
+/** Only nativeToolName values activate schemas; Code Mode aliases activate their owning Tool. */
+const Result = Schema.Struct({
+	toolNames: Schema.Array(Name).check(Schema.isMaxLength(64), Schema.isUnique()),
+	matches: Schema.Array(Match).check(Schema.isMaxLength(64))
+});
+/** Invalid custom results, unsupported documentation, and bounded output failures remain typed. */
+var ToolDiscoveryError = class extends Schema.TaggedError()("ToolDiscoveryError", {
+	reason: Schema.Literals([
+		"invalid-catalogue",
+		"invalid-matches",
+		"unknown-match",
+		"invalid-schema",
+		"limit-exceeded"
+	]),
+	message: Schema.String.check(Schema.isMaxLength(1024))
+}) {};
+const MatchIds = Schema.Array(EntryId).check(Schema.isMaxLength(1024), Schema.isUnique());
+const Bounds = Schema.Struct({
+	maxResults: Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 64
+	})),
+	maxResultBytes: Schema.Int.check(Schema.isBetween({
+		minimum: 256,
+		maximum: 262144
+	})),
+	namespaceDescriptions: Schema.Record(Namespace, NamespaceDescription)
+});
+const entryId = (entry) => entry.kind === "native" ? `native:${entry.tool.name}` : `code-mode:${entry.nativeToolName}:${entry.namespace}.${entry.method}`;
+const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const defaultSearch = (request, catalogue, entries) => {
+	const terms = request.query.trim().toLowerCase().split(/\s+/);
+	return catalogue.filter((entry) => {
+		const original = entries.get(entry.id);
+		if (original === void 0) return false;
+		const text = [
+			entry.name,
+			entry.namespace ?? "",
+			entry.method ?? "",
+			Tool.getDescription(original.tool) ?? "",
+			entry.namespaceDescription ?? ""
+		].join(" ").toLowerCase();
+		return terms.every((term) => text.includes(term));
+	}).map((entry) => entry.id);
+};
+/**
+* Build one native discover_tools Tool and its singleton Toolkit/handler Layer. Include the
+* Tool beside the application's existing native Tools. The engine owns catalogue authority
+* and applies successful native selections after a complete Tool batch; the handler mutates
+* no exposure state. Default search matches all case-insensitive whitespace-separated terms
+* against names, descriptions, methods and namespace hints, ordered by catalogue id.
+*/
+const make = (options = {}) => {
+	const bounds = Schema.decodeSync(Bounds)({
+		maxResults: options.maxResults ?? 8,
+		maxResultBytes: options.maxResultBytes ?? 32768,
+		namespaceDescriptions: options.namespaceDescriptions ?? {}
+	});
+	const search = options.search;
+	const declaredFailure = options.failure ?? Schema.Never;
+	const tool = Tool.make("discover_tools", {
+		description: options.description ?? "Find available tools using short search terms and an optional exact namespace. All terms must match a name, description or namespace hint, ignoring case. Returned native tools become available next turn. Code Mode matches document namespace methods and select their owning execution tool.",
+		parameters: Parameters,
+		success: Result,
+		failure: Schema.Union([declaredFailure, ToolDiscoveryError]),
+		failureMode: "error",
+		dependencies: [CurrentToolCatalog]
+	}).annotate(DiscoveryTool, true).annotate(PinnedTool, true).annotate(Tool.Readonly, true).annotate(ToolExecutionClass, "readonly");
+	const toolkit = Toolkit.make(tool);
+	const handlers = toolkit.toLayer(Effect.gen(function* () {
+		const searchServices = yield* Effect.context();
+		return toolkit.of({ discover_tools: Effect.fn("ToolDiscovery.discover_tools")(function* (request) {
+			const entries = (yield* CurrentToolCatalog).entries.filter((entry) => request.namespace === void 0 || entry.namespace === request.namespace).toSorted((left, right) => compare(entryId(left), entryId(right)));
+			const catalogue = [];
+			const byId = /* @__PURE__ */ new Map();
+			for (const entry of entries) {
+				const id = entryId(entry);
+				if (byId.has(id)) return yield* ToolDiscoveryError.make({
+					reason: "invalid-catalogue",
+					message: "The visible catalogue contains duplicate entry identities"
+				});
+				const description = Tool.getDescription(entry.tool);
+				const namespaceDescription = entry.namespace === void 0 || !Object.hasOwn(bounds.namespaceDescriptions, entry.namespace) ? void 0 : bounds.namespaceDescriptions[entry.namespace];
+				const descriptor = yield* Schema.decodeEffect(Descriptor)({
+					id,
+					kind: entry.kind,
+					name: entry.tool.name,
+					nativeToolName: entry.nativeToolName,
+					...entry.namespace === void 0 ? {} : { namespace: entry.namespace },
+					...entry.kind === "code-mode" ? { method: entry.method } : {},
+					...description === void 0 ? {} : { description: description.length > 2048 ? `${description.slice(0, 2047)}…` : description },
+					...namespaceDescription === void 0 ? {} : { namespaceDescription }
+				}).pipe(Effect.mapError(() => ToolDiscoveryError.make({
+					reason: "invalid-catalogue",
+					message: "The visible catalogue contains invalid metadata"
+				})));
+				catalogue.push(Object.freeze(descriptor));
+				byId.set(id, entry);
+			}
+			const ids = search === void 0 ? defaultSearch(request, catalogue, byId) : yield* Effect.scoped(search(request, Object.freeze(catalogue))).pipe(Effect.provideContext(searchServices));
+			const checkedIds = yield* Schema.decodeEffect(MatchIds)(ids).pipe(Effect.mapError(() => ToolDiscoveryError.make({
+				reason: "invalid-matches",
+				message: "Search must return at most 1024 unique catalogue entry ids"
+			})));
+			if (checkedIds.some((id) => !byId.has(id))) return yield* ToolDiscoveryError.make({
+				reason: "unknown-match",
+				message: "Search returned an entry outside the visible catalogue"
+			});
+			const descriptors = new Map(catalogue.map((descriptor) => [descriptor.id, descriptor]));
+			const matches = [];
+			for (const id of checkedIds.slice(0, bounds.maxResults)) {
+				const entry = byId.get(id);
+				const descriptor = descriptors.get(id);
+				if (entry === void 0 || descriptor === void 0) return yield* ToolDiscoveryError.make({
+					reason: "unknown-match",
+					message: "Search returned an entry outside the visible catalogue"
+				});
+				if (Tool.isProviderDefined(entry.tool)) return yield* ToolDiscoveryError.make({
+					reason: "invalid-schema",
+					message: "Provider-defined Tools do not expose application handler documentation"
+				});
+				const schemas = yield* Effect.try({
+					try: () => ({
+						parameters: Tool.getJsonSchema(entry.tool),
+						success: Tool.getJsonSchemaFromSchema(entry.tool.successSchema)
+					}),
+					catch: () => ToolDiscoveryError.make({
+						reason: "invalid-schema",
+						message: "A selected Tool cannot be documented as JSON Schema"
+					})
+				});
+				const match = yield* Schema.decodeUnknownEffect(Match)({
+					...descriptor,
+					...schemas
+				}).pipe(Effect.mapError(() => ToolDiscoveryError.make({
+					reason: "invalid-schema",
+					message: "A selected Tool's documentation is outside the JSON surface"
+				})));
+				matches.push(match);
+			}
+			const result = {
+				toolNames: [...new Set(matches.map((match) => match.nativeToolName))],
+				matches
+			};
+			const encoded = yield* Schema.encodeEffect(Schema.fromJsonString(Result))(result).pipe(Effect.mapError(() => ToolDiscoveryError.make({
+				reason: "invalid-schema",
+				message: "Discovery documentation could not be encoded"
+			})));
+			if (utf8ByteLength(encoded) > bounds.maxResultBytes) return yield* ToolDiscoveryError.make({
+				reason: "limit-exceeded",
+				message: "Selected documentation exceeds the result byte limit; narrow the search"
+			});
+			return result;
+		}) });
+	}));
+	return Object.freeze({
+		tool,
+		toolkit,
+		handlers
+	});
+};
+//#endregion
+export { Descriptor, Match, Parameters, Result, ToolDiscoveryError, make, ToolDiscovery_exports as t };
+
+//# sourceMappingURL=ToolDiscovery.mjs.map

package/dist/capabilities/ToolDiscovery.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolDiscovery.mjs","names":[],"sources":["../../src/capabilities/ToolDiscovery.ts"],"sourcesContent":["import { Effect, Schema, type Scope } from \"effect\";\nimport { Tool, Toolkit } from \"effect/unstable/ai\";\n\nimport { utf8ByteLength } from \"../core/internal/utf8.ts\";\nimport { DiscoveryTool, PinnedTool } from \"../core/ToolExposure.ts\";\nimport { ToolExecutionClass } from \"../engine/DurableStep.ts\";\nimport { CurrentToolCatalog, type CatalogEntry } from \"../engine/ToolExposure.ts\";\n\nconst Name = Schema.NonEmptyString.check(Schema.isMaxLength(256));\nconst Namespace = Schema.NonEmptyString.check(Schema.isMaxLength(128));\nconst Description = Schema.String.check(Schema.isMaxLength(2_048));\nconst NamespaceDescription = Schema.String.check(Schema.isMaxLength(512));\nconst EntryId = Schema.NonEmptyString.check(Schema.isMaxLength(1_024));\n\n/** Search text is bounded and literal; namespace selects one exact host-declared group. */\nexport const Parameters = Schema.Struct({\n  query: Schema.NonEmptyString.check(Schema.isMaxLength(512), Schema.isPattern(/\\S/)),\n  namespace: Schema.optionalKey(Namespace),\n});\n\n/** Metadata given to custom search only after host visibility and inherited grants are applied. */\nexport class Descriptor extends Schema.Class<Descriptor>(\n  \"@effect-agent/capabilities/ToolDiscovery/Descriptor\",\n)({\n  id: EntryId,\n  kind: Schema.Literals([\"native\", \"code-mode\"]),\n  name: Name,\n  nativeToolName: Name,\n  namespace: Schema.optionalKey(Namespace),\n  method: Schema.optionalKey(Schema.NonEmptyString.check(Schema.isMaxLength(128))),\n  description: Schema.optionalKey(Description),\n  namespaceDescription: Schema.optionalKey(NamespaceDescription),\n}) {}\n\n/**\n * Selected metadata and canonical encoded Tool Schemas. Provider-specific model schema\n * transformations do not change the wire values documented for application handlers.\n */\nexport class Match extends Schema.Class<Match>(\"@effect-agent/capabilities/ToolDiscovery/Match\")({\n  ...Descriptor.fields,\n  parameters: Schema.Json,\n  success: Schema.Json,\n}) {}\n\n/** Only nativeToolName values activate schemas; Code Mode aliases activate their owning Tool. */\nexport const Result = Schema.Struct({\n  toolNames: Schema.Array(Name).check(Schema.isMaxLength(64), Schema.isUnique()),\n  matches: Schema.Array(Match).check(Schema.isMaxLength(64)),\n});\n\n/** Invalid custom results, unsupported documentation, and bounded output failures remain typed. */\nexport class ToolDiscoveryError extends Schema.TaggedError<ToolDiscoveryError>()(\n  \"ToolDiscoveryError\",\n  {\n    reason: Schema.Literals([\n      \"invalid-catalogue\",\n      \"invalid-matches\",\n      \"unknown-match\",\n      \"invalid-schema\",\n      \"limit-exceeded\",\n    ]),\n    message: Schema.String.check(Schema.isMaxLength(1_024)),\n  },\n) {}\n\nconst MatchIds = Schema.Array(EntryId).check(Schema.isMaxLength(1_024), Schema.isUnique());\n\nconst Bounds = Schema.Struct({\n  maxResults: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 64 })),\n  maxResultBytes: Schema.Int.check(Schema.isBetween({ minimum: 256, maximum: 256 * 1024 })),\n  namespaceDescriptions: Schema.Record(Namespace, NamespaceDescription),\n});\n\nexport interface Options<Failure extends Schema.Top = typeof Schema.Never, Requirements = never> {\n  /** Optional generic instructions. Namespace names and hints are never appended here. */\n  readonly description?: string | undefined;\n  /** Maximum returned catalogue entries, default 8 and at most 64. */\n  readonly maxResults?: number | undefined;\n  /** Complete JSON-encoded result budget, default 32768 and at most 262144 UTF-8 bytes. */\n  readonly maxResultBytes?: number | undefined;\n  /** Short category hints returned only for namespaces present in the visible catalogue. */\n  readonly namespaceDescriptions?: Readonly<Record<string, string>> | undefined;\n  /** Schema of the custom search's expected failures; defaults to Schema.Never. */\n  readonly failure?: Failure | undefined;\n  /**\n   * Rank unique Descriptor.id values, never tool names. Native tools and each Code Mode alias\n   * have distinct identities. Every returned id is checked before the result limit is applied.\n   * The catalogue is already filtered by the optional exact namespace and current authority.\n   * Services are captured with the handler Layer; temporary resources close after each search.\n   */\n  readonly search?:\n    | ((\n        request: typeof Parameters.Type,\n        catalogue: ReadonlyArray<Descriptor>,\n      ) => Effect.Effect<ReadonlyArray<string>, Failure[\"Type\"], Requirements>)\n    | undefined;\n}\n\nconst entryId = (entry: CatalogEntry): string =>\n  entry.kind === \"native\"\n    ? `native:${entry.tool.name}`\n    : `code-mode:${entry.nativeToolName}:${entry.namespace}.${entry.method}`;\n\nconst compare = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);\n\nconst defaultSearch = (\n  request: typeof Parameters.Type,\n  catalogue: ReadonlyArray<Descriptor>,\n  entries: ReadonlyMap<string, CatalogEntry>,\n): ReadonlyArray<string> => {\n  const terms = request.query.trim().toLowerCase().split(/\\s+/);\n\n  return catalogue\n    .filter((entry) => {\n      const original = entries.get(entry.id);\n\n      if (original === undefined) return false;\n\n      const text = [\n        entry.name,\n        entry.namespace ?? \"\",\n        entry.method ?? \"\",\n        Tool.getDescription(original.tool) ?? \"\",\n        entry.namespaceDescription ?? \"\",\n      ]\n        .join(\" \")\n        .toLowerCase();\n\n      return terms.every((term) => text.includes(term));\n    })\n    .map((entry) => entry.id);\n};\n\n/**\n * Build one native discover_tools Tool and its singleton Toolkit/handler Layer. Include the\n * Tool beside the application's existing native Tools. The engine owns catalogue authority\n * and applies successful native selections after a complete Tool batch; the handler mutates\n * no exposure state. Default search matches all case-insensitive whitespace-separated terms\n * against names, descriptions, methods and namespace hints, ordered by catalogue id.\n */\nexport const make = <Failure extends Schema.Top = typeof Schema.Never, Requirements = never>(\n  options: Options<Failure, Requirements> = {},\n) => {\n  const bounds = Schema.decodeSync(Bounds)({\n    maxResults: options.maxResults ?? 8,\n    maxResultBytes: options.maxResultBytes ?? 32 * 1024,\n    namespaceDescriptions: options.namespaceDescriptions ?? {},\n  });\n\n  const search = options.search;\n\n  const declaredFailure: Schema.Codec<\n    Failure[\"Type\"],\n    Failure[\"Encoded\"],\n    Failure[\"DecodingServices\"],\n    Failure[\"EncodingServices\"]\n  > = options.failure ?? Schema.Never;\n\n  const tool = Tool.make(\"discover_tools\", {\n    description:\n      options.description ??\n      \"Find available tools using short search terms and an optional exact namespace. All terms must match a name, description or namespace hint, ignoring case. Returned native tools become available next turn. Code Mode matches document namespace methods and select their owning execution tool.\",\n    parameters: Parameters,\n    success: Result,\n    failure: Schema.Union([declaredFailure, ToolDiscoveryError]),\n    failureMode: \"error\",\n    dependencies: [CurrentToolCatalog],\n  })\n    .annotate(DiscoveryTool, true)\n    .annotate(PinnedTool, true)\n    .annotate(Tool.Readonly, true)\n    .annotate(ToolExecutionClass, \"readonly\");\n\n  // Restore the known singleton name; native ToolsByName leaves its conditional deferred\n  // over the generic failure Schema. This assertion changes no Schema or runtime value.\n  const toolkit = Toolkit.make(tool) as unknown as Toolkit.Toolkit<{\n    readonly discover_tools: typeof tool;\n  }>;\n\n  const handlers = toolkit.toLayer(\n    Effect.gen(function* () {\n      const searchServices = yield* Effect.context<Exclude<Requirements, Scope.Scope>>();\n\n      return toolkit.of({\n        discover_tools: Effect.fn(\"ToolDiscovery.discover_tools\")(function* (request) {\n          const snapshot = yield* CurrentToolCatalog;\n\n          const entries = snapshot.entries\n            .filter(\n              (entry) => request.namespace === undefined || entry.namespace === request.namespace,\n            )\n            .toSorted((left, right) => compare(entryId(left), entryId(right)));\n\n          const catalogue: Array<Descriptor> = [];\n          const byId = new Map<string, CatalogEntry>();\n\n          for (const entry of entries) {\n            const id = entryId(entry);\n\n            if (byId.has(id)) {\n              return yield* ToolDiscoveryError.make({\n                reason: \"invalid-catalogue\",\n                message: \"The visible catalogue contains duplicate entry identities\",\n              });\n            }\n            const description = Tool.getDescription(entry.tool);\n\n            const namespaceDescription =\n              entry.namespace === undefined ||\n              !Object.hasOwn(bounds.namespaceDescriptions, entry.namespace)\n                ? undefined\n                : bounds.namespaceDescriptions[entry.namespace];\n\n            const descriptor = yield* Schema.decodeEffect(Descriptor)({\n              id,\n              kind: entry.kind,\n              name: entry.tool.name,\n              nativeToolName: entry.nativeToolName,\n              ...(entry.namespace === undefined ? {} : { namespace: entry.namespace }),\n              ...(entry.kind === \"code-mode\" ? { method: entry.method } : {}),\n              ...(description === undefined\n                ? {}\n                : {\n                    description:\n                      description.length > 2_048 ? `${description.slice(0, 2_047)}…` : description,\n                  }),\n              ...(namespaceDescription === undefined ? {} : { namespaceDescription }),\n            }).pipe(\n              Effect.mapError(() =>\n                ToolDiscoveryError.make({\n                  reason: \"invalid-catalogue\",\n                  message: \"The visible catalogue contains invalid metadata\",\n                }),\n              ),\n            );\n\n            catalogue.push(Object.freeze(descriptor));\n            byId.set(id, entry);\n          }\n\n          const ids =\n            search === undefined\n              ? defaultSearch(request, catalogue, byId)\n              : yield* Effect.scoped(search(request, Object.freeze(catalogue))).pipe(\n                  Effect.provideContext(searchServices),\n                );\n\n          const checkedIds = yield* Schema.decodeEffect(MatchIds)(ids).pipe(\n            Effect.mapError(() =>\n              ToolDiscoveryError.make({\n                reason: \"invalid-matches\",\n                message: \"Search must return at most 1024 unique catalogue entry ids\",\n              }),\n            ),\n          );\n\n          if (checkedIds.some((id) => !byId.has(id))) {\n            return yield* ToolDiscoveryError.make({\n              reason: \"unknown-match\",\n              message: \"Search returned an entry outside the visible catalogue\",\n            });\n          }\n\n          const descriptors = new Map(catalogue.map((descriptor) => [descriptor.id, descriptor]));\n          const matches: Array<Match> = [];\n\n          for (const id of checkedIds.slice(0, bounds.maxResults)) {\n            const entry = byId.get(id);\n            const descriptor = descriptors.get(id);\n\n            if (entry === undefined || descriptor === undefined) {\n              return yield* ToolDiscoveryError.make({\n                reason: \"unknown-match\",\n                message: \"Search returned an entry outside the visible catalogue\",\n              });\n            }\n            if (Tool.isProviderDefined(entry.tool)) {\n              return yield* ToolDiscoveryError.make({\n                reason: \"invalid-schema\",\n                message: \"Provider-defined Tools do not expose application handler documentation\",\n              });\n            }\n\n            const schemas = yield* Effect.try({\n              try: () => ({\n                parameters: Tool.getJsonSchema(entry.tool),\n                success: Tool.getJsonSchemaFromSchema(entry.tool.successSchema),\n              }),\n              catch: () =>\n                ToolDiscoveryError.make({\n                  reason: \"invalid-schema\",\n                  message: \"A selected Tool cannot be documented as JSON Schema\",\n                }),\n            });\n\n            const match = yield* Schema.decodeUnknownEffect(Match)({\n              ...descriptor,\n              ...schemas,\n            }).pipe(\n              Effect.mapError(() =>\n                ToolDiscoveryError.make({\n                  reason: \"invalid-schema\",\n                  message: \"A selected Tool's documentation is outside the JSON surface\",\n                }),\n              ),\n            );\n\n            matches.push(match);\n          }\n\n          const result = {\n            toolNames: [...new Set(matches.map((match) => match.nativeToolName))],\n            matches,\n          };\n\n          const encoded = yield* Schema.encodeEffect(Schema.fromJsonString(Result))(result).pipe(\n            Effect.mapError(() =>\n              ToolDiscoveryError.make({\n                reason: \"invalid-schema\",\n                message: \"Discovery documentation could not be encoded\",\n              }),\n            ),\n          );\n\n          if (utf8ByteLength(encoded) > bounds.maxResultBytes) {\n            return yield* ToolDiscoveryError.make({\n              reason: \"limit-exceeded\",\n              message: \"Selected documentation exceeds the result byte limit; narrow the search\",\n            });\n          }\n\n          return result;\n        }),\n      });\n    }),\n  );\n\n  return Object.freeze({ tool, toolkit, handlers });\n};\n"],"mappings":"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"}

package/dist/capabilities/WebCapture.d.mts

@@ -0,0 +1,163 @@
+import { L as PageScrapeGroup, S as PageCaptureResponseFormat, l as PageCaptureEngine, o as PageCapture } from "../PageCapture-Df8Xwskw.mjs";
+import { Tool } from "effect/unstable/ai";
+import { Layer, Schema } from "effect";
+declare namespace WebCapture_d_exports {
+  export { WebCaptureAction, WebCaptureDefinition, WebCaptureExtractDefinition, WebCaptureExtractLayerRequirements, WebCaptureExtractOptions, WebCaptureExtractParameters, WebCaptureExtractTool, WebCaptureExtractTools, WebCaptureFailure, WebCaptureOptions, WebCaptureParameters, WebCaptureScrapeDefinition, WebCaptureScrapeOptions, WebCaptureScrapeParameters, WebCaptureScrapeSuccess, WebCaptureScrapeTool, WebCaptureScrapeTools, WebCaptureSuccess, WebCaptureTool, WebCaptureTools, make, makeExtract, makeScrape };
+}
+/** The model-selectable capture actions the first slice exposes. */
+declare const WebCaptureAction: Schema.Literals<readonly ["markdown", "content", "links"]>;
+type WebCaptureAction = typeof WebCaptureAction.Type;
+/** Model-decoded parameters: one absolute https URL plus one capture action. */
+declare const WebCaptureParameters: Schema.Struct<{
+  readonly url: Schema.NonEmptyString;
+  readonly action: Schema.Literals<readonly ["markdown", "content", "links"]>;
+}>;
+/** Model-decoded extraction parameters: one absolute https URL. */
+declare const WebCaptureExtractParameters: Schema.Struct<{
+  readonly url: Schema.NonEmptyString;
+}>;
+/** Model-decoded scrape parameters: one allowed URL and 1..64 CSS selectors. */
+declare const WebCaptureScrapeParameters: Schema.Struct<{
+  readonly url: Schema.NonEmptyString;
+  readonly selectors: Schema.$Array<Schema.NonEmptyString>;
+}>;
+declare const WebCaptureSuccess_base: Schema.Class<WebCaptureSuccess, Schema.Struct<{
+  readonly url: Schema.NonEmptyString;
+  readonly action: Schema.Literals<readonly ["markdown", "content", "links"]>;
+  readonly markdown: Schema.optionalKey<Schema.String>;
+  readonly html: Schema.optionalKey<Schema.String>;
+  readonly links: Schema.optionalKey<Schema.$Array<Schema.NonEmptyString>>;
+}>, {}>;
+/**
+ * The bounded model-visible capture success. Exactly the field matching the
+ * requested action is present.
+ */
+declare class WebCaptureSuccess extends WebCaptureSuccess_base {}
+declare const WebCaptureFailure_base: Schema.Class<WebCaptureFailure, Schema.TaggedStruct<"WebCaptureFailure", {
+  readonly errorTag: Schema.NonEmptyString;
+  readonly message: Schema.String;
+  readonly retryAfterMillis: Schema.optionalKey<Schema.Natural>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The bounded model-visible failure envelope. `failureMode: "return"` turns
+ * it into a failed Tool result, so a model can pick a different target or
+ * action without a blind retry. `retryAfterMillis` carries the platform's
+ * backoff hint when the capture was rate-limited.
+ */
+declare class WebCaptureFailure extends WebCaptureFailure_base {}
+declare const WebCaptureScrapeSuccess_base: Schema.Class<WebCaptureScrapeSuccess, Schema.Struct<{
+  readonly url: Schema.NonEmptyString;
+  readonly groups: Schema.$Array<typeof PageScrapeGroup>;
+}>, {}>;
+/** The bounded model-visible selector scrape success. */
+declare class WebCaptureScrapeSuccess extends WebCaptureScrapeSuccess_base {}
+/** The native Effect AI Tool created by `WebCapture.make`. */
+type WebCaptureTool<Name extends string> = Tool.Tool<Name, {
+  readonly parameters: typeof WebCaptureParameters;
+  readonly success: typeof WebCaptureSuccess;
+  readonly failure: typeof WebCaptureFailure;
+  readonly failureMode: "return";
+}>;
+/** The native Effect AI Tool created by `WebCapture.makeExtract`. */
+type WebCaptureExtractTool<Name extends string, S extends Schema.Top> = Tool.Tool<Name, {
+  readonly parameters: typeof WebCaptureExtractParameters;
+  readonly success: S;
+  readonly failure: typeof WebCaptureFailure;
+  readonly failureMode: "return";
+}, S["DecodingServices"]>;
+/** The native Effect AI Tool created by `WebCapture.makeScrape`. */
+type WebCaptureScrapeTool<Name extends string> = Tool.Tool<Name, {
+  readonly parameters: typeof WebCaptureScrapeParameters;
+  readonly success: typeof WebCaptureScrapeSuccess;
+  readonly failure: typeof WebCaptureFailure;
+  readonly failureMode: "return";
+}>;
+/** Singleton Tool record provided by one web-capture handler Layer. */
+type WebCaptureTools<Name extends string> = { readonly [Key in Name]: WebCaptureTool<Name>; };
+/** Singleton Tool record provided by one extraction handler Layer. */
+type WebCaptureExtractTools<Name extends string, S extends Schema.Top> = { readonly [Key in Name]: WebCaptureExtractTool<Name, S>; };
+/** Singleton Tool record provided by one selector-scrape handler Layer. */
+type WebCaptureScrapeTools<Name extends string> = { readonly [Key in Name]: WebCaptureScrapeTool<Name>; };
+/** Construction requirements of a schema-shaped extraction handler Layer. */
+type WebCaptureExtractLayerRequirements<S extends Schema.Top> = PageCapture | S["DecodingServices"];
+interface WebCaptureSharedOptions {
+  /** Model-visible description; the builder appends the policy contract. */
+  readonly description: string;
+  /**
+   * Allowed target hosts: bare host names (`docs.example.com`) or one-level
+   * wildcards (`*.example.com`, matching the apex and every subdomain). The
+   * list must be non-empty — capture is deny-by-default (security spec §9).
+   */
+  readonly urls: ReadonlyArray<string>;
+  /** Rendering engine; defaults to `chromium`. */
+  readonly engine?: PageCaptureEngine | undefined;
+  /**
+   * Response byte budget measured on the UTF-8 encoded platform response.
+   * Default 131072 (128 KiB); construction fails closed outside
+   * [1024, 1048576].
+   */
+  readonly maxResponseBytes?: number | undefined;
+}
+interface WebCaptureOptions extends WebCaptureSharedOptions {
+  /** Model-selectable actions; defaults to every first-slice action. */
+  readonly actions?: ReadonlyArray<WebCaptureAction> | undefined;
+}
+interface WebCaptureExtractOptions<S extends Schema.Top> extends WebCaptureSharedOptions {
+  /**
+   * The extraction Schema. Its derived JSON Schema shapes the platform-side
+   * extraction, and the untrusted result is decoded through this exact
+   * Schema before it becomes the Tool success. Any decoding services remain
+   * visible in the handler Layer's requirements.
+   */
+  readonly schema: S;
+  /** Optional natural-language guidance sent alongside the derived schema. */
+  readonly prompt?: string | undefined;
+}
+interface WebCaptureScrapeOptions extends WebCaptureSharedOptions {}
+/**
+ * An immutable web-capture definition: one model-facing Tool over a fixed
+ * URL policy, plus the handler Layer that runs captures through the
+ * `PageCapture` port. It owns no acquired resources.
+ */
+interface WebCaptureDefinition<Name extends string> {
+  readonly name: Name;
+  /** The assembled model-facing description including the policy contract. */
+  readonly description: string;
+  /** The normalized allowed-host patterns. */
+  readonly urlPatterns: ReadonlyArray<string>;
+  readonly actions: ReadonlyArray<WebCaptureAction>;
+  readonly engine: PageCaptureEngine;
+  readonly maxResponseBytes: number;
+  /** The ordinary Effect AI Tool to include in the model-facing Toolkit. */
+  readonly tool: WebCaptureTool<Name>;
+  /** Handler Layer; the `PageCapture` requirement stays visible in `R`. */
+  readonly handlers: Layer.Layer<Tool.HandlersFor<WebCaptureTools<Name>>, never, PageCapture>;
+}
+/** An immutable schema-shaped extraction definition. */
+interface WebCaptureExtractDefinition<Name extends string, S extends Schema.Top> {
+  readonly name: Name;
+  readonly description: string;
+  readonly urlPatterns: ReadonlyArray<string>;
+  readonly engine: PageCaptureEngine;
+  readonly maxResponseBytes: number;
+  /** The JSON Schema document derived from the extraction Schema. */
+  readonly responseFormat: PageCaptureResponseFormat;
+  readonly tool: WebCaptureExtractTool<Name, S>;
+  readonly handlers: Layer.Layer<Tool.HandlersFor<WebCaptureExtractTools<Name, S>>, never, WebCaptureExtractLayerRequirements<S>>;
+}
+/** An immutable selector-scrape definition. */
+interface WebCaptureScrapeDefinition<Name extends string> {
+  readonly name: Name;
+  readonly description: string;
+  readonly urlPatterns: ReadonlyArray<string>;
+  readonly engine: PageCaptureEngine;
+  readonly maxResponseBytes: number;
+  readonly tool: WebCaptureScrapeTool<Name>;
+  readonly handlers: Layer.Layer<Tool.HandlersFor<WebCaptureScrapeTools<Name>>, never, PageCapture>;
+}
+declare const make: <const Name extends string>(name: Name, options: WebCaptureOptions) => WebCaptureDefinition<Name>;
+declare const makeExtract: <const Name extends string, S extends Schema.Top>(name: Name, options: WebCaptureExtractOptions<S>) => WebCaptureExtractDefinition<Name, S>;
+declare const makeScrape: <const Name extends string>(name: Name, options: WebCaptureScrapeOptions) => WebCaptureScrapeDefinition<Name>;
+//#endregion
+export { WebCaptureAction, WebCaptureDefinition, WebCaptureExtractDefinition, WebCaptureExtractLayerRequirements, WebCaptureExtractOptions, WebCaptureExtractParameters, WebCaptureExtractTool, WebCaptureExtractTools, WebCaptureFailure, WebCaptureOptions, WebCaptureParameters, WebCaptureScrapeDefinition, WebCaptureScrapeOptions, WebCaptureScrapeParameters, WebCaptureScrapeSuccess, WebCaptureScrapeTool, WebCaptureScrapeTools, WebCaptureSuccess, WebCaptureTool, WebCaptureTools, make, makeExtract, makeScrape, WebCapture_d_exports as t };
+//# sourceMappingURL=WebCapture.d.mts.map