effect-agent 0.1.0-beta.12 → 0.1.0-beta.121

package/dist/capabilities/CodeMode.d.mts

@@ -0,0 +1,157 @@
+import { s as ToolBroker } from "../ToolBroker-DWs4tZra.mjs";
+import { CodeExecutionLimits, CodeExecutionNamespace, CodeExecutor } from "../sandbox/CodeExecutor.mjs";
+import { Tool } from "effect/unstable/ai";
+import { Cause, Effect, Layer, Schema, Scope } from "effect";
+declare namespace CodeMode_d_exports {
+  export { CodeModeDefinition, CodeModeDescriptionError, CodeModeFailure, CodeModeLayerRequirements, CodeModeNamespaces, CodeModeOptions, CodeModeParameters, CodeModePassReport, CodeModeSelectedRecord, CodeModeSelectedTool, CodeModeSuccess, CodeModeTool, CodeModeTools, make };
+}
+/** A pass-local report, available to the host even when the caller interrupts execution. */
+export declare const CodeModePassReport: Schema.Struct<{
+  readonly status: Schema.Literals<readonly ["completed", "failed", "interrupted", "defect"]>;
+  readonly calls: Schema.$Array<Schema.Struct<{
+    readonly sequenceIndex: Schema.Natural;
+    readonly toolName: Schema.String;
+    readonly status: Schema.Literals<readonly ["not-started", "succeeded", "failed", "uncertain"]>;
+    readonly errorTag: Schema.optionalKey<Schema.String>;
+  }>>;
+}>;
+export type CodeModePassReport = typeof CodeModePassReport.Type;
+/** Model-decoded Code Mode parameters: one async function expression. */
+export declare const CodeModeParameters: Schema.Struct<{
+  readonly code: Schema.NonEmptyString;
+}>;
+declare const CodeModeSuccess_base: Schema.Class<CodeModeSuccess, Schema.Struct<{
+  readonly result: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+  readonly logs: Schema.$Array<Schema.String>;
+}>, {}>;
+/**
+ * The bounded model-visible success: the program's JSON result plus captured
+ * logs, both already passed through the aggregate egress budget (CAP-016).
+ */
+export declare class CodeModeSuccess extends CodeModeSuccess_base {}
+declare const CodeModeFailure_base: Schema.Class<CodeModeFailure, Schema.TaggedStruct<"CodeModeFailure", {
+  readonly errorTag: Schema.NonEmptyString;
+  readonly message: Schema.String;
+  readonly logs: Schema.$Array<Schema.String>;
+  readonly thrown: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+  /** Invocation-ordered evidence that fits the egress budget. This is not a replay plan. */
+  readonly calls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    readonly sequenceIndex: Schema.Natural;
+    readonly toolName: Schema.String;
+    readonly status: Schema.Literals<readonly ["not-started", "succeeded", "failed", "uncertain"]>;
+    readonly errorTag: Schema.optionalKey<Schema.String>;
+  }>>>;
+  readonly omittedCalls: Schema.optionalKey<Schema.Natural>;
+}>, Cause.YieldableError>;
+/**
+ * The bounded model-visible failure envelope. `failureMode: "return"` turns
+ * it into a failed Tool result, so a model can correct a failing program
+ * without a blind retry; it carries the same bounded log capture as success
+ * plus the bounded thrown value where one exists, all inside the same
+ * aggregate egress budget (CAP-016).
+ */
+export declare class CodeModeFailure extends CodeModeFailure_base {}
+declare const CodeModeDescriptionError_base: Schema.Class<CodeModeDescriptionError, Schema.TaggedStruct<"CodeModeDescriptionError", {
+  readonly reason: Schema.Literals<readonly ["invalid-selection", "unknown-method", "invalid-bound", "limit-exceeded"]>;
+  readonly message: Schema.String;
+}>, Cause.YieldableError>;
+/** A selective documentation request is invalid or cannot fit its declared byte budget. */
+export declare class CodeModeDescriptionError extends CodeModeDescriptionError_base {}
+/** The namespace-record shape accepted by `CodeMode.make`. */
+export type CodeModeNamespaces = Record<string, Record<string, Tool.Any>>;
+/**
+ * Union of every Tool selected across all namespaces, computed distributively
+ * per namespace: indexing the namespace union with the INTERSECTION of method
+ * keys would erase every Tool once two namespaces have disjoint methods.
+ */
+export type CodeModeSelectedTool<Namespaces extends CodeModeNamespaces> = { [Namespace in keyof Namespaces]: Namespaces[Namespace][keyof Namespaces[Namespace]]; }[keyof Namespaces];
+/** The selected Tools re-keyed by their own Tool names. */
+export type CodeModeSelectedRecord<Namespaces extends CodeModeNamespaces> = { readonly [T in CodeModeSelectedTool<Namespaces> as T["name"]]: T; };
+/**
+ * The native Effect AI Tool created by `CodeMode.make` (CAP-014). Its only
+ * per-call dependency is the engine-provided `ToolBroker`; the `CodeExecutor`
+ * and every selected handler and redaction service are construction requirements of the handler
+ * Layer instead, so they stay visible in the composed `R`.
+ */
+export type CodeModeTool<Name extends string> = Tool.Tool<Name, {
+  readonly parameters: typeof CodeModeParameters;
+  readonly success: typeof CodeModeSuccess;
+  readonly failure: typeof CodeModeFailure;
+  readonly failureMode: "return";
+}, ToolBroker>;
+/** Singleton Tool record provided by one Code Mode handler Layer. */
+export type CodeModeTools<Name extends string> = { readonly [Key in Name]: CodeModeTool<Name>; };
+/** Construction requirements of the Code Mode handler Layer. */
+export type CodeModeLayerRequirements<Namespaces extends CodeModeNamespaces, RedactionRequirements = never> = CodeExecutor | Exclude<RedactionRequirements, Scope.Scope> | Tool.HandlersFor<CodeModeSelectedRecord<Namespaces>> | Tool.HandlerServices<CodeModeSelectedTool<Namespaces>>;
+export interface CodeModeOptions<Namespaces extends CodeModeNamespaces, RedactionRequirements = never> {
+  /** Model-visible description; the builder appends the sandbox contract. */
+  readonly description: string;
+  /** Include all sandbox declarations in the model-facing description. Defaults to true. */
+  readonly includeDeclarations?: boolean | undefined;
+  /**
+   * Explicit allowlist: namespace name → method name → native Effect AI
+   * Tool. Reads and mutations are allowed; calls requiring additional approval fail closed.
+   */
+  readonly tools: Namespaces;
+  /** Executor limits for one pass; a bounded default applies when omitted. */
+  readonly limits?: CodeExecutionLimits | undefined;
+  /**
+   * Aggregate model-visible egress budget in UTF-8 bytes across the final
+   * result, captured logs, and any thrown value (CAP-016). Default 65536.
+   */
+  readonly maxEgressBytes?: number | undefined;
+  /**
+   * Host-only ephemeral report after executor resources and invocation fibers close, including
+   * failure, defect, and interruption. It contains no arguments/results and is never a checkpoint.
+   * Keep this total callback bounded; its services are captured with the handler Layer.
+   */
+  readonly onPassExit?: ((report: CodeModePassReport) => Effect.Effect<void, never, RedactionRequirements>) | undefined;
+  /**
+   * Optional aggregate redaction pass applied to the model-visible egress
+   * before the byte budget. Its services are acquired with the handler Layer;
+   * temporary resources close with each redaction invocation.
+   * It must be total; a defect stays a defect.
+   */
+  readonly redactEgress?: ((egress: {
+    readonly result: Schema.Json;
+    readonly logs: ReadonlyArray<string>;
+  }) => Effect.Effect<{
+    readonly result: Schema.Json;
+    readonly logs: ReadonlyArray<string>;
+  }, never, RedactionRequirements>) | undefined;
+}
+/**
+ * An immutable Code Mode definition: one model-facing Tool over an explicit
+ * allowlist, plus the handler Layer that runs generated programs through the
+ * `CodeExecutor` port and the engine-owned broker. It owns no acquired
+ * resources.
+ */
+export interface CodeModeDefinition<Name extends string, Namespaces extends CodeModeNamespaces, RedactionRequirements = never> {
+  readonly name: Name;
+  /** The assembled model-facing description, optionally including all declarations. */
+  readonly description: string;
+  /** Rendered TypeScript declarations of the sandbox globals (documentation only). */
+  readonly declarations: string;
+  /**
+   * Render complete encoded-schema declarations for 1–64 unique, exact namespace.method names.
+   * The UTF-8 byte limit defaults to 16384 and must be an integer from 1 through 262144.
+   * Oversized documentation fails rather than truncating a declaration. This host operation
+   * does not authorize a model to see the selected methods; filter selections by current
+   * visibility and inherited grants before returning its output to a model.
+   */
+  readonly describe: (methods: ReadonlyArray<string>, options?: {
+    readonly maxBytes?: number | undefined;
+  }) => Effect.Effect<string, CodeModeDescriptionError>;
+  /** The executor-facing namespace catalog derived from the allowlist. */
+  readonly namespaces: ReadonlyArray<CodeExecutionNamespace>;
+  readonly limits: CodeExecutionLimits;
+  readonly maxEgressBytes: number;
+  /** The ordinary Effect AI Tool to include in the model-facing Toolkit. */
+  readonly tool: CodeModeTool<Name>;
+  /** Handler Layer; selected handler requirements stay visible in `R`. */
+  readonly handlers: Layer.Layer<Tool.HandlersFor<CodeModeTools<Name>>, never, CodeModeLayerRequirements<Namespaces, RedactionRequirements>>;
+}
+declare const make: <const Name extends string, Namespaces extends CodeModeNamespaces, RedactionRequirements = never>(name: Name, options: CodeModeOptions<Namespaces, RedactionRequirements>) => CodeModeDefinition<Name, Namespaces, RedactionRequirements>;
+//#endregion
+export { make, CodeMode_d_exports as t };
+//# sourceMappingURL=CodeMode.d.mts.map

package/dist/capabilities/CodeMode.mjs

@@ -0,0 +1,522 @@
+import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
+import { n as utf8ByteLength } from "../utf8-DchGZRBd.mjs";
+import { r as IncludesCatalogDocumentation, t as AdditionalToolCatalog } from "../ToolExposure-C93U1sPu.mjs";
+import { t as CurrentToolCatalog } from "../ToolExposure-9uF_Yo0T.mjs";
+import { ToolExecutionClass } from "../engine/DurableStep.mjs";
+import { ProgrammaticCallRecord, ToolBroker } from "../engine/ToolBroker.mjs";
+import { NetworkDisabled } from "../sandbox/Sandbox.mjs";
+import { CodeExecutionHost, CodeExecutionLimits, CodeExecutionNamespace, CodeExecutionRequest, CodeExecutor, JsIdentifier } from "../sandbox/CodeExecutor.mjs";
+import { Tool, Toolkit } from "effect/unstable/ai";
+import { Cause, Context, Duration, Effect, Exit, Option, Schema } from "effect";
+//#region src/capabilities/CodeMode.ts
+var CodeMode_exports = /* @__PURE__ */ __exportAll({
+	CodeModeDescriptionError: () => CodeModeDescriptionError,
+	CodeModeFailure: () => CodeModeFailure,
+	CodeModeParameters: () => CodeModeParameters,
+	CodeModePassReport: () => CodeModePassReport,
+	CodeModeSuccess: () => CodeModeSuccess,
+	make: () => make
+});
+/**
+* Code Mode (D-035, ADR-0017; capability spec §9.1): one native Effect AI
+* Tool whose input is bounded JavaScript source, executed in one isolated
+* `CodeExecutor` pass that may call an explicit construction-time allowlist
+* of existing Tools through typed sandbox globals and the engine-owned
+* `ToolBroker`. The builder follows the Delegation pattern: an explicit
+* record of selected Tools plus namespace mapping fixed at construction,
+* returning an ordinary Tool and a handler Layer, with no ambient registry
+* (CAP-014). Deployment class `E` only.
+*/
+const maxFailureTextLength = 4096;
+const BoundedFailureText = Schema.String.check(Schema.isMaxLength(maxFailureTextLength));
+const BoundedErrorTag = Schema.NonEmptyString.check(Schema.isMaxLength(256));
+const BoundedLogLine = Schema.String.check(Schema.isMaxLength(16384));
+const BoundedLogs = Schema.Array(BoundedLogLine).check(Schema.isMaxLength(4096));
+const BoundedCode = Schema.NonEmptyString.check(Schema.isMaxLength(524288));
+/** A pass-local report, available to the host even when the caller interrupts execution. */
+const CodeModePassReport = Schema.Struct({
+	status: Schema.Literals([
+		"completed",
+		"failed",
+		"interrupted",
+		"defect"
+	]),
+	calls: Schema.Array(ProgrammaticCallRecord)
+});
+const encodedJsonByteLength = (value) => {
+	try {
+		const encoded = JSON.stringify(value);
+		return encoded === void 0 ? void 0 : utf8ByteLength(encoded);
+	} catch {
+		return;
+	}
+};
+/** Model-decoded Code Mode parameters: one async function expression. */
+const CodeModeParameters = Schema.Struct({ code: BoundedCode });
+/**
+* The bounded model-visible success: the program's JSON result plus captured
+* logs, both already passed through the aggregate egress budget (CAP-016).
+*/
+var CodeModeSuccess = class extends Schema.Class("@effect-agent/capabilities/CodeModeSuccess")({
+	result: Schema.Json,
+	logs: BoundedLogs
+}) {};
+/**
+* The bounded model-visible failure envelope. `failureMode: "return"` turns
+* it into a failed Tool result, so a model can correct a failing program
+* without a blind retry; it carries the same bounded log capture as success
+* plus the bounded thrown value where one exists, all inside the same
+* aggregate egress budget (CAP-016).
+*/
+var CodeModeFailure = class extends Schema.TaggedError()("CodeModeFailure", {
+	errorTag: BoundedErrorTag,
+	message: BoundedFailureText,
+	logs: BoundedLogs,
+	thrown: Schema.optionalKey(Schema.Json),
+	/** Invocation-ordered evidence that fits the egress budget. This is not a replay plan. */
+	calls: Schema.optionalKey(Schema.Array(ProgrammaticCallRecord)),
+	omittedCalls: Schema.optionalKey(Schema.Natural)
+}) {};
+/** A selective documentation request is invalid or cannot fit its declared byte budget. */
+var CodeModeDescriptionError = class extends Schema.TaggedError()("CodeModeDescriptionError", {
+	reason: Schema.Literals([
+		"invalid-selection",
+		"unknown-method",
+		"invalid-bound",
+		"limit-exceeded"
+	]),
+	message: BoundedFailureText
+}) {};
+const DescriptionMethods = Schema.Array(Schema.NonEmptyString.check(Schema.isMaxLength(257))).check(Schema.isMinLength(1), Schema.isMaxLength(64), Schema.isUnique());
+const DescriptionByteLimit = Schema.Int.check(Schema.isBetween({
+	minimum: 1,
+	maximum: 262144
+}));
+const defaultLimits = CodeExecutionLimits.make({
+	maxSourceBytes: 262144,
+	maxWallTime: Duration.seconds(30),
+	maxLogBytes: 262144,
+	maxResultBytes: 1048576,
+	maxHostCalls: 64,
+	maxHostCallArgumentBytes: 262144,
+	maxHostCallResultBytes: 1048576
+});
+const defaultMaxEgressBytes = 65536;
+const MAX_RENDER_DEPTH = 24;
+const isJsonSchemaRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const renderJsonSchemaType = (schema, defs, depth, indent) => {
+	if (depth > MAX_RENDER_DEPTH) throw new Error("Code Mode declaration rendering exceeded its depth bound");
+	if (!isJsonSchemaRecord(schema)) throw new Error(`Code Mode cannot render the JSON schema fragment ${JSON.stringify(schema)}`);
+	const reference = schema.$ref;
+	if (typeof reference === "string") {
+		const match = /^#\/\$defs\/(.+)$/.exec(reference);
+		const key = match === null ? void 0 : match[1].replaceAll("~1", "/").replaceAll("~0", "~");
+		const resolved = key === void 0 ? void 0 : defs[key];
+		if (resolved === void 0) throw new Error(`Code Mode cannot resolve the JSON schema reference ${reference}`);
+		return renderJsonSchemaType(resolved, defs, depth + 1, indent);
+	}
+	if (Array.isArray(schema.enum)) return schema.enum.map((value) => JSON.stringify(value)).join(" | ");
+	if ("const" in schema) return JSON.stringify(schema.const);
+	const union = schema.anyOf ?? schema.oneOf;
+	if (Array.isArray(union)) return union.map((member) => renderJsonSchemaType(member, defs, depth + 1, indent)).join(" | ");
+	const type = schema.type;
+	if (Array.isArray(type)) return type.map((member) => renderJsonSchemaType({
+		...schema,
+		type: member
+	}, defs, depth + 1, indent)).join(" | ");
+	switch (type) {
+		case "string": return "string";
+		case "number":
+		case "integer": return "number";
+		case "boolean": return "boolean";
+		case "null": return "null";
+		case "array":
+			if (!("items" in schema)) throw new Error("Code Mode cannot render an array schema without items");
+			return `ReadonlyArray<${renderJsonSchemaType(schema.items, defs, depth + 1, indent)}>`;
+		case "object":
+		case void 0:
+			if (isJsonSchemaRecord(schema.properties)) {
+				const required = Array.isArray(schema.required) ? schema.required : [];
+				const inner = `${indent}  `;
+				const fields = Object.entries(schema.properties).map(([key, property]) => {
+					const optional = required.includes(key) ? "" : "?";
+					const rendered = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+					return `${inner}readonly ${rendered}${optional}: ${renderJsonSchemaType(property, defs, depth + 1, inner)};`;
+				});
+				return fields.length === 0 ? "{}" : `{\n${fields.join("\n")}\n${indent}}`;
+			}
+			if (isJsonSchemaRecord(schema.additionalProperties)) return `Record<string, ${renderJsonSchemaType(schema.additionalProperties, defs, depth + 1, indent)}>`;
+			if (type === "object" && !("properties" in schema) && !("additionalProperties" in schema)) return "Record<string, unknown>";
+	}
+	throw new Error(`Code Mode cannot render the JSON schema fragment ${JSON.stringify(schema).slice(0, 200)}; fix or simplify the Tool's Schema`);
+};
+const renderTopLevel = (jsonSchema, indent) => {
+	const defs = isJsonSchemaRecord(jsonSchema) && isJsonSchemaRecord(jsonSchema.$defs) ? jsonSchema.$defs : {};
+	return renderJsonSchemaType(jsonSchema, defs, 0, indent);
+};
+const decodeIdentifier = Schema.decodeUnknownOption(JsIdentifier);
+const renderDeclarations = (methods) => {
+	const namespaces = /* @__PURE__ */ new Map();
+	for (const method of methods) {
+		const existing = namespaces.get(method.namespace) ?? [];
+		existing.push(method);
+		namespaces.set(method.namespace, existing);
+	}
+	return [...namespaces.entries()].map(([namespace, members]) => {
+		return `declare const ${namespace}: {\n${members.map((member) => {
+			const parameters = renderTopLevel(Tool.getJsonSchema(member.tool), "  ");
+			const success = renderTopLevel(Tool.getJsonSchemaFromSchema(member.tool.successSchema), "  ");
+			const safeDescription = member.tool.description?.replaceAll("*/", "*\\/").replaceAll(/\s*\n\s*/g, " ");
+			return `${safeDescription === void 0 ? "" : `  /** ${safeDescription} */\n`}  ${member.method}(input: ${parameters}): Promise<${success}>;`;
+		}).join("\n")}\n};`;
+	}).join("\n\n");
+};
+const truncationMarker = "… logs truncated by the egress budget";
+const MAX_EGRESS_LOG_LINE_CHARACTERS = 16e3;
+/**
+* Budget charge of one log line as it actually crosses to the model: the
+* JSON-encoded string (quotes, escapes) plus one array separator. Charging
+* raw UTF-8 would undercount model-visible bytes for escape-heavy content.
+*/
+const encodedLogLineBytes = (line) => {
+	try {
+		return utf8ByteLength(JSON.stringify(line)) + 1;
+	} catch {
+		return Number.MAX_SAFE_INTEGER;
+	}
+};
+const budgetedLogs = (logs, remainingBytes) => {
+	const kept = [];
+	let used = 0;
+	let truncated = false;
+	for (const raw of logs) {
+		const line = raw.length > MAX_EGRESS_LOG_LINE_CHARACTERS ? `${raw.slice(0, 15999)}…` : raw;
+		const bytes = encodedLogLineBytes(line);
+		if (kept.length >= 4096 || used + bytes > remainingBytes) {
+			truncated = true;
+			break;
+		}
+		kept.push(line);
+		used += bytes;
+	}
+	if (truncated) {
+		const markerBytes = encodedLogLineBytes(truncationMarker);
+		while (kept.length > 0 && used + markerBytes > remainingBytes) used -= encodedLogLineBytes(kept.pop() ?? "");
+		if (markerBytes <= remainingBytes) kept.push(truncationMarker);
+	}
+	return kept;
+};
+const boundedMessage = (message) => message.slice(0, maxFailureTextLength);
+const executionFailureMessage = (error) => {
+	switch (error._tag) {
+		case "CodeExecutionTimeoutError": return `The program exceeded its ${Duration.format(error.maxWallTime)} ${error.kind} budget`;
+		case "CodeOutputLimitError": return `The ${error.surface} limit of ${error.limit} bytes was exceeded (${error.observed} bytes observed)`;
+		case "CodeHostCallLimitError": return `The pass exceeded its executor cap of ${error.limit} host calls`;
+		default: return error.message;
+	}
+};
+/** UTF-8-aware truncation so a message can never exceed the aggregate budget. */
+const truncateToUtf8Bytes = (value, maxBytes) => {
+	if (utf8ByteLength(value) <= maxBytes) return value;
+	let output = "";
+	let used = 0;
+	for (const character of value) {
+		const bytes = utf8ByteLength(character);
+		if (used + bytes + 3 > maxBytes) break;
+		output += character;
+		used += bytes;
+	}
+	return `${output}…`;
+};
+const make = (name, options) => {
+	const limits = options.limits ?? defaultLimits;
+	const maxEgressBytes = options.maxEgressBytes ?? defaultMaxEgressBytes;
+	if (!Number.isSafeInteger(maxEgressBytes) || maxEgressBytes < 256 || maxEgressBytes > 4194304) throw new Error(`Code Mode maxEgressBytes must be an integer between 256 and 4194304; received ${String(maxEgressBytes)}`);
+	const methods = [];
+	const toolsByName = /* @__PURE__ */ new Map();
+	const methodToTool = /* @__PURE__ */ new Map();
+	for (const [namespace, namespaceMethods] of Object.entries(options.tools)) {
+		if (Option.isNone(decodeIdentifier(namespace))) throw new Error(`Code Mode namespace ${namespace} is not a valid JavaScript identifier`);
+		const entries = Object.entries(namespaceMethods);
+		if (entries.length === 0) throw new Error(`Code Mode namespace ${namespace} declares no methods`);
+		for (const [method, tool] of entries) {
+			if (Option.isNone(decodeIdentifier(method))) throw new Error(`Code Mode method ${namespace}.${method} is not a valid JavaScript identifier`);
+			const approval = tool.needsApproval;
+			if (approval !== void 0 && approval !== false) throw new Error(`Code Mode rejects Tool ${tool.name} (${namespace}.${method}): approval-requiring Tools cannot be invoked programmatically in the ephemeral slice`);
+			const existing = toolsByName.get(tool.name);
+			if (existing !== void 0 && existing !== tool) throw new Error(`Code Mode selected two different Tools named ${tool.name}; Tool names must identify one Tool`);
+			toolsByName.set(tool.name, tool);
+			methodToTool.set(`${namespace}.${method}`, tool.name);
+			methods.push({
+				namespace,
+				method,
+				tool
+			});
+		}
+	}
+	if (methods.length === 0) throw new Error("Code Mode requires at least one allowlisted Tool");
+	const declarations = renderDeclarations(methods);
+	const methodsByPath = new Map(methods.map((method) => [`${method.namespace}.${method.method}`, method]));
+	const describe = Effect.fn("CodeMode.describe")(function* (selected, options) {
+		const paths = yield* Schema.decodeEffect(DescriptionMethods)(selected).pipe(Effect.mapError(() => CodeModeDescriptionError.make({
+			reason: "invalid-selection",
+			message: "Select between 1 and 64 unique namespace.method names, each at most 257 characters"
+		})));
+		const maxBytes = yield* Schema.decodeEffect(DescriptionByteLimit)(options?.maxBytes ?? 16384).pipe(Effect.mapError(() => CodeModeDescriptionError.make({
+			reason: "invalid-bound",
+			message: "The documentation byte limit must be an integer between 1 and 262144"
+		})));
+		const selectedMethods = [];
+		for (const path of paths) {
+			const method = methodsByPath.get(path);
+			if (method === void 0) return yield* CodeModeDescriptionError.make({
+				reason: "unknown-method",
+				message: "The selection contains a method outside this Code Mode allowlist"
+			});
+			selectedMethods.push(method);
+		}
+		const documentation = renderDeclarations(selectedMethods);
+		if (utf8ByteLength(documentation) > maxBytes) return yield* CodeModeDescriptionError.make({
+			reason: "limit-exceeded",
+			message: `The selected declarations exceed the ${maxBytes}-byte documentation limit; select fewer methods or raise the limit`
+		});
+		return documentation;
+	});
+	const namespaces = [...new Set(methods.map((method) => method.namespace))].map((namespace) => CodeExecutionNamespace.make({
+		name: namespace,
+		methods: methods.filter((method) => method.namespace === namespace).map((method) => method.method)
+	}));
+	const description = [
+		options.description,
+		"",
+		"The `code` argument must be one JavaScript async function expression; the sandbox invokes it exactly once with no arguments. It runs isolated with no ambient network, filesystem, environment, or secrets. Return one JSON value. `console.log` output is captured within a bounded budget and returned alongside the result.",
+		"Namespace methods return Promises. An expected Tool failure rejects with a JSON envelope carrying a stable `_tag`; catch it to branch. Use Promise.all for independent calls; the host bounds concurrency. Await every call you need. Writes may complete before a failure: inspect call outcomes and never blindly retry a program.",
+		...options.includeDeclarations === false ? [] : [
+			"",
+			"Sandbox globals:",
+			"```ts",
+			declarations,
+			"```"
+		]
+	].join("\n");
+	const tool = Tool.make(name, {
+		description,
+		parameters: CodeModeParameters,
+		success: CodeModeSuccess,
+		failure: CodeModeFailure,
+		failureMode: "return"
+	}).annotate(Tool.Readonly, false).annotate(ToolExecutionClass, "uncertain").annotate(IncludesCatalogDocumentation, options.includeDeclarations !== false).annotate(AdditionalToolCatalog, Object.freeze(methods.map((method) => Object.freeze({ ...method })))).addDependency(ToolBroker);
+	const outerToolkit = Toolkit.make(tool);
+	/**
+	* The nested namespace record collapses into one Toolkit keyed by exact
+	* Tool names. The assertion restores the name-keyed record type TypeScript
+	* cannot compute from `Map` iteration; construction above guarantees the
+	* name uniqueness the type states.
+	*/
+	const selectedToolkit = Toolkit.make(...toolsByName.values());
+	const executionRequest = (code, visibleNamespaces) => CodeExecutionRequest.make({
+		language: "javascript",
+		source: code,
+		namespaces: visibleNamespaces,
+		network: NetworkDisabled.make({}),
+		limits
+	});
+	const routeHostCall = (pass, hostCall, visiblePaths) => Effect.gen(function* () {
+		const path = `${hostCall.namespace}.${hostCall.method}`;
+		const toolName = visiblePaths === void 0 || visiblePaths.has(path) ? methodToTool.get(path) : void 0;
+		if (toolName === void 0) return {
+			_tag: "CodeHostCallFailure",
+			error: {
+				_tag: "UnknownCodeModeMethod",
+				message: "The requested method is not available in this pass"
+			}
+		};
+		const outcome = yield* pass.invoke({
+			toolName,
+			encodedArguments: hostCall.argument
+		});
+		switch (outcome._tag) {
+			case "ProgrammaticCallSuccess": {
+				const value = decodeBrokerJson(outcome.encodedResult);
+				return Option.isSome(value) ? {
+					_tag: "CodeHostCallSuccess",
+					value: value.value
+				} : {
+					_tag: "CodeHostCallFailure",
+					error: brokerProtocolEnvelope
+				};
+			}
+			case "ProgrammaticCallFailure": {
+				const value = decodeBrokerJson(outcome.encodedResult);
+				return {
+					_tag: "CodeHostCallFailure",
+					error: Option.isSome(value) ? value.value : brokerProtocolEnvelope
+				};
+			}
+			case "ProgrammaticCallError": return {
+				_tag: "CodeHostCallFailure",
+				error: {
+					_tag: outcome.errorTag,
+					message: outcome.message
+				}
+			};
+		}
+	});
+	const build = Effect.gen(function* () {
+		const captured = yield* Effect.context();
+		const redactionServices = yield* Effect.context();
+		const configuredRedactor = options.redactEgress;
+		const redact = configuredRedactor === void 0 ? void 0 : (egress) => Effect.scoped(configuredRedactor(egress)).pipe(Effect.updateContext((current) => Context.merge(current, redactionServices)));
+		const withHandler = yield* selectedToolkit;
+		const executor = yield* CodeExecutor;
+		const successEgress = (execution) => Effect.gen(function* () {
+			let egress = {
+				result: execution.value,
+				logs: execution.logs
+			};
+			if (redact !== void 0) egress = yield* redact(egress);
+			const resultBytes = encodedJsonByteLength(egress.result);
+			if (resultBytes === void 0 || resultBytes > maxEgressBytes) return yield* CodeModeFailure.make({
+				errorTag: "CodeModeEgressExceeded",
+				message: `The program result of ${resultBytes ?? "unencodable"} bytes exceeds the ${maxEgressBytes}-byte model-visible egress budget; return a smaller value`,
+				logs: budgetedLogs(egress.logs, Math.max(0, maxEgressBytes - 256))
+			});
+			return CodeModeSuccess.make({
+				result: egress.result,
+				logs: budgetedLogs(egress.logs, maxEgressBytes - resultBytes)
+			});
+		});
+		/**
+		* The failure half of the aggregate egress policy (CAP-016): the configured
+		* redaction pass covers failure logs and thrown values exactly like success
+		* egress — a program cannot leak by logging and then throwing — and the
+		* message itself is bounded by the budget, not only by its own schema cap.
+		*/
+		const failureEgress = (error) => Effect.gen(function* () {
+			if (error._tag === "ToolBrokerUnavailableError" || error._tag === "ToolBrokerConfigurationError") return CodeModeFailure.make({
+				errorTag: error._tag,
+				message: truncateToUtf8Bytes(boundedMessage(error.message), maxEgressBytes),
+				logs: []
+			});
+			let logs = "logs" in error ? error.logs : [];
+			let candidateThrown = error._tag === "CodeProgramFailedError" ? error.thrown : void 0;
+			if (redact !== void 0) {
+				const redacted = yield* redact({
+					result: candidateThrown ?? null,
+					logs
+				});
+				logs = redacted.logs;
+				candidateThrown = candidateThrown === void 0 ? void 0 : redacted.result;
+			}
+			const message = truncateToUtf8Bytes(boundedMessage(executionFailureMessage(error)), maxEgressBytes);
+			const messageBytes = utf8ByteLength(message);
+			const candidateBytes = candidateThrown === void 0 ? void 0 : encodedJsonByteLength(candidateThrown);
+			const includeThrown = candidateThrown !== void 0 && candidateBytes !== void 0 && messageBytes + candidateBytes <= maxEgressBytes;
+			const remaining = Math.max(0, maxEgressBytes - messageBytes - (includeThrown ? candidateBytes ?? 0 : 0));
+			return CodeModeFailure.make({
+				errorTag: error._tag,
+				message,
+				logs: budgetedLogs(logs, remaining),
+				...includeThrown ? { thrown: candidateThrown } : {}
+			});
+		});
+		const invoke = Effect.fn(`CodeMode.${name}`)(function* (parameters) {
+			const broker = yield* ToolBroker;
+			const catalogue = yield* Effect.serviceOption(CurrentToolCatalog);
+			const visiblePaths = Option.isNone(catalogue) ? void 0 : new Set(catalogue.value.entries.flatMap((entry) => entry.kind === "code-mode" && entry.nativeToolName === name && methodsByPath.get(`${entry.namespace}.${entry.method}`)?.tool.name === entry.tool.name ? [`${entry.namespace}.${entry.method}`] : []));
+			const visibleNamespaces = visiblePaths === void 0 ? namespaces : namespaces.flatMap((namespace) => {
+				const allowed = namespace.methods.filter((method) => visiblePaths.has(`${namespace.name}.${method}`));
+				return allowed.length === 0 ? [] : [CodeExecutionNamespace.make({
+					name: namespace.name,
+					methods: allowed
+				})];
+			});
+			let calls = [];
+			return yield* Effect.gen(function* () {
+				const pass = yield* broker.openPass(withHandler, {
+					maxResultBytes: limits.maxHostCallResultBytes,
+					concurrency: limits.maxHostCallConcurrency ?? 4
+				});
+				const host = CodeExecutionHost.of({ call: (hostCall) => routeHostCall(pass, hostCall, visiblePaths) });
+				return yield* executor.execute(executionRequest(parameters.code, visibleNamespaces)).pipe(Effect.provideService(CodeExecutionHost, host), Effect.scoped, Effect.onExit((exit) => Effect.gen(function* () {
+					calls = yield* pass.snapshot;
+					if (options.onPassExit !== void 0) yield* Effect.scoped(options.onPassExit({
+						status: Exit.isSuccess(exit) ? "completed" : Cause.hasInterrupts(exit.cause) ? "interrupted" : Cause.hasDies(exit.cause) ? "defect" : "failed",
+						calls
+					})).pipe(Effect.provideContext(redactionServices));
+				})));
+			}).pipe(Effect.scoped, Effect.provideService(ToolBroker, broker), Effect.provideContext(captured)).pipe(Effect.catch((error) => failureEgress(error).pipe(Effect.flatMap(Effect.fail))), Effect.flatMap(successEgress), Effect.mapError((failure) => {
+				if (calls.length === 0) return failure;
+				const complete = CodeModeFailure.make({
+					errorTag: failure.errorTag,
+					message: failure.message,
+					logs: failure.logs,
+					...failure.thrown === void 0 ? {} : { thrown: failure.thrown },
+					calls,
+					omittedCalls: 0
+				});
+				if ((encodedJsonByteLength(complete) ?? Infinity) <= maxEgressBytes) return complete;
+				const base = {
+					errorTag: failure.errorTag,
+					message: truncateToUtf8Bytes(failure.message, Math.min(256, maxEgressBytes / 4)),
+					logs: []
+				};
+				const kept = [];
+				for (const call of calls) {
+					const candidate = CodeModeFailure.make({
+						...base,
+						calls: [...kept, call],
+						omittedCalls: calls.length - kept.length - 1
+					});
+					if ((encodedJsonByteLength(candidate) ?? Infinity) > maxEgressBytes) break;
+					kept.push(call);
+				}
+				return CodeModeFailure.make({
+					...base,
+					calls: kept,
+					omittedCalls: calls.length - kept.length
+				});
+			}));
+		});
+		return { [name]: invoke };
+	});
+	/**
+	* TypeScript cannot unify the two spellings of the singleton Tool record
+	* (`CodeModeTools<Name>` versus the toolkit's name-remapped form) over a
+	* generic `Name`, nor reduce the deferred `Exclude` when `toLayer`
+	* subtracts what `build` consumed; the assertions pin the layer to its
+	* documented requirement surface and never bypass validation.
+	*/
+	const handlers = outerToolkit.toLayer(build);
+	return Object.freeze({
+		name,
+		description,
+		declarations,
+		describe,
+		namespaces,
+		limits,
+		maxEgressBytes,
+		tool,
+		handlers
+	});
+};
+/**
+* Fail-closed JSON boundary for broker outcomes: hostile values can throw
+* from trap getters during decode, and a value outside the JSON surface must
+* become a typed failure envelope — never a fabricated success.
+*/
+const decodeBrokerJson = (value) => {
+	try {
+		return Schema.decodeUnknownOption(Schema.Json)(value);
+	} catch {
+		return Option.none();
+	}
+};
+const brokerProtocolEnvelope = {
+	_tag: "CodeModeProtocolError",
+	message: "The broker returned a value outside the JSON surface"
+};
+//#endregion
+export { CodeModeDescriptionError, CodeModeFailure, CodeModeParameters, CodeModePassReport, CodeModeSuccess, make, CodeMode_exports as t };
+
+//# sourceMappingURL=CodeMode.mjs.map