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

package/dist/capabilities/Budget.mjs

@@ -0,0 +1,346 @@
+import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
+import { Clock, Duration, Effect, Ref, Schema } from "effect";
+//#region src/capabilities/Budget.ts
+var Budget_exports = /* @__PURE__ */ __exportAll({
+	BudgetExceeded: () => BudgetExceeded,
+	BudgetNodeConflict: () => BudgetNodeConflict,
+	InvalidBudgetHierarchy: () => InvalidBudgetHierarchy,
+	UsageBudgetLimits: () => UsageBudgetLimits,
+	UsageBudgetNodeConfig: () => UsageBudgetNodeConfig,
+	UsageDelta: () => UsageDelta,
+	UsageTotals: () => UsageTotals,
+	makeUsageBudget: () => makeUsageBudget,
+	makeUsageBudgetRoot: () => makeUsageBudgetRoot
+});
+const Natural = Schema.Natural;
+const BudgetLevel = Schema.Literals([
+	"global",
+	"tenant",
+	"agent",
+	"thread",
+	"run"
+]);
+/** Fixed units avoid floating-point currency accounting: costs are micro-USD. */
+var UsageTotals = class extends Schema.Class("@effect-agent/capabilities/UsageTotals")({
+	/** Total input tokens across every model call, INCLUDING cache reads and writes at par. */
+	inputTokens: Natural,
+	outputTokens: Natural,
+	/** Informational split of `inputTokens` served from the provider prompt cache; never separately limited. */
+	cacheReadInputTokens: Natural,
+	/** Informational split of `inputTokens` written to the provider prompt cache; never separately limited. */
+	cacheWriteInputTokens: Natural,
+	/** The most recent model call's input tokens — the live model-context estimate (CAP-017). */
+	lastInputTokens: Natural,
+	/** The most recent model call's output tokens. */
+	lastOutputTokens: Natural,
+	toolCalls: Natural,
+	costMicrousd: Natural,
+	elapsedMillis: Natural
+}) {};
+/** Increment recorded at one model/tool accounting boundary. */
+var UsageDelta = class extends Schema.Class("@effect-agent/capabilities/UsageDelta")({
+	/** `1` for a model-response boundary, `0` for a mid-pass tool charge; gates last-call tracking. */
+	modelCalls: Natural,
+	/** Total input tokens of this boundary, INCLUDING cache reads and writes at par. */
+	inputTokens: Natural,
+	outputTokens: Natural,
+	/** Informational split of `inputTokens` served from the provider prompt cache; never separately limited. */
+	cacheReadInputTokens: Natural,
+	/** Informational split of `inputTokens` written to the provider prompt cache; never separately limited. */
+	cacheWriteInputTokens: Natural,
+	toolCalls: Natural,
+	costMicrousd: Natural
+}) {};
+/** All optional limits are finite when present; absent means not configured. */
+var UsageBudgetLimits = class extends Schema.Class("@effect-agent/capabilities/UsageBudgetLimits")({
+	maxInputTokens: Schema.optionalKey(Natural),
+	maxOutputTokens: Schema.optionalKey(Natural),
+	maxToolCalls: Schema.optionalKey(Natural),
+	maxCostMicrousd: Schema.optionalKey(Natural),
+	maxDurationMillis: Schema.optionalKey(Natural)
+}) {};
+/** Identity and local limits for one node in a global-to-Run budget hierarchy. */
+var UsageBudgetNodeConfig = class extends Schema.Class("@effect-agent/capabilities/UsageBudgetNodeConfig")({
+	level: BudgetLevel,
+	id: Schema.NonEmptyString,
+	limits: UsageBudgetLimits
+}) {};
+/** Typed finite-budget rejection. A rejected increment is not committed at any hierarchy level. */
+var BudgetExceeded = class extends Schema.TaggedError()("BudgetExceeded", {
+	scopeLevel: BudgetLevel,
+	scopeId: Schema.NonEmptyString,
+	limit: Schema.Literals([
+		"input-tokens",
+		"output-tokens",
+		"tool-calls",
+		"cost",
+		"duration"
+	]),
+	limitValue: Natural,
+	observedValue: Natural
+}) {};
+/** A child budget must move strictly inward through the declared hierarchy. */
+var InvalidBudgetHierarchy = class extends Schema.TaggedError()("InvalidBudgetHierarchy", {
+	parentLevel: BudgetLevel,
+	childLevel: BudgetLevel
+}) {};
+/** A child `level:id` is already registered with different limits; neither set may win silently. */
+var BudgetNodeConflict = class extends Schema.TaggedError()("BudgetNodeConflict", {
+	scopeLevel: BudgetLevel,
+	scopeId: Schema.NonEmptyString
+}) {};
+const levelOrder = {
+	global: 0,
+	tenant: 1,
+	agent: 2,
+	thread: 3,
+	run: 4
+};
+const emptyTotals = (elapsedMillis = 0) => UsageTotals.make({
+	inputTokens: 0,
+	outputTokens: 0,
+	cacheReadInputTokens: 0,
+	cacheWriteInputTokens: 0,
+	lastInputTokens: 0,
+	lastOutputTokens: 0,
+	toolCalls: 0,
+	costMicrousd: 0,
+	elapsedMillis
+});
+const withElapsed = (node, now) => UsageTotals.make({
+	...node.totals,
+	elapsedMillis: Math.max(0, now - node.startedAt)
+});
+const addUsage = (node, delta, now) => UsageTotals.make({
+	inputTokens: node.totals.inputTokens + delta.inputTokens,
+	outputTokens: node.totals.outputTokens + delta.outputTokens,
+	cacheReadInputTokens: node.totals.cacheReadInputTokens + delta.cacheReadInputTokens,
+	cacheWriteInputTokens: node.totals.cacheWriteInputTokens + delta.cacheWriteInputTokens,
+	lastInputTokens: delta.modelCalls > 0 ? delta.inputTokens : node.totals.lastInputTokens,
+	lastOutputTokens: delta.modelCalls > 0 ? delta.outputTokens : node.totals.lastOutputTokens,
+	toolCalls: node.totals.toolCalls + delta.toolCalls,
+	costMicrousd: node.totals.costMicrousd + delta.costMicrousd,
+	elapsedMillis: Math.max(0, now - node.startedAt)
+});
+const exceeded = (node, totals) => {
+	const limits = node.config.limits;
+	const checks = [
+		[
+			"input-tokens",
+			limits.maxInputTokens,
+			totals.inputTokens
+		],
+		[
+			"output-tokens",
+			limits.maxOutputTokens,
+			totals.outputTokens
+		],
+		[
+			"tool-calls",
+			limits.maxToolCalls,
+			totals.toolCalls
+		],
+		[
+			"cost",
+			limits.maxCostMicrousd,
+			totals.costMicrousd
+		],
+		[
+			"duration",
+			limits.maxDurationMillis,
+			totals.elapsedMillis
+		]
+	];
+	for (const [limit, limitValue, observedValue] of checks) if (limitValue !== void 0 && observedValue > limitValue) return BudgetExceeded.make({
+		scopeLevel: node.config.level,
+		scopeId: node.config.id,
+		limit,
+		limitValue,
+		observedValue
+	});
+};
+const sameLimits = (a, b) => a.maxInputTokens === b.maxInputTokens && a.maxOutputTokens === b.maxOutputTokens && a.maxToolCalls === b.maxToolCalls && a.maxCostMicrousd === b.maxCostMicrousd && a.maxDurationMillis === b.maxDurationMillis;
+const nodeKeyComponent = (config) => `${config.level}:${encodeURIComponent(JSON.stringify(config.id))}`;
+const durationExceeded = (node, now) => {
+	const limitValue = node.config.limits.maxDurationMillis ?? 0;
+	return BudgetExceeded.make({
+		scopeLevel: node.config.level,
+		scopeId: node.config.id,
+		limit: "duration",
+		limitValue,
+		observedValue: Math.max(limitValue + 1, now - node.startedAt)
+	});
+};
+/** Reclaim one released leaf and any newly unowned ancestors on its fixed hierarchy path. */
+const pruneRetiredHierarchy = (nodes, hierarchy) => {
+	for (let index = hierarchy.length - 1; index >= 0; index -= 1) {
+		const candidateKey = hierarchy[index];
+		if (candidateKey === void 0) continue;
+		const candidate = nodes.get(candidateKey);
+		if (candidate === void 0) continue;
+		if (candidate.handles.size > 0) break;
+		const childPrefix = `${candidateKey}/`;
+		if ([...nodes.keys()].some((otherKey) => otherKey.startsWith(childPrefix))) break;
+		nodes.delete(candidateKey);
+	}
+	return nodes;
+};
+const makeNode = (ledger, key, ancestors, config, handleId) => {
+	const hierarchy = [...ancestors, key];
+	const retiredDefect = () => Effect.die(/* @__PURE__ */ new Error(`Usage budget handle ${config.level}:${config.id} was used after retirement`));
+	const liveHierarchy = (state) => {
+		const current = state.nodes.get(key);
+		if (current === void 0 || !current.handles.has(handleId)) return void 0;
+		const nodes = [];
+		for (const ancestorKey of hierarchy) {
+			const node = state.nodes.get(ancestorKey);
+			if (node === void 0) return void 0;
+			nodes.push(node);
+		}
+		return nodes;
+	};
+	const readLiveHierarchy = Ref.modify(ledger, (state) => [liveHierarchy(state), state]);
+	const snapshot = Effect.gen(function* () {
+		const now = yield* Clock.currentTimeMillis;
+		const nodes = yield* readLiveHierarchy;
+		if (nodes === void 0) return yield* retiredDefect();
+		const node = nodes[nodes.length - 1];
+		if (node === void 0) return yield* retiredDefect();
+		return withElapsed(node, now);
+	});
+	const guard = (effect) => Effect.gen(function* () {
+		const now = yield* Clock.currentTimeMillis;
+		const nodes = yield* readLiveHierarchy;
+		if (nodes === void 0) return yield* retiredDefect();
+		let deadline;
+		for (const node of nodes) {
+			const current = withElapsed(node, now);
+			const alreadyExceeded = exceeded(node, current);
+			if (alreadyExceeded !== void 0) return yield* alreadyExceeded;
+			const maxDuration = node.config.limits.maxDurationMillis;
+			if (maxDuration !== void 0) {
+				const remaining = maxDuration - current.elapsedMillis;
+				if (remaining <= 0) return yield* durationExceeded(node, now);
+				if (deadline === void 0 || remaining < deadline.remaining) deadline = {
+					remaining,
+					node
+				};
+			}
+		}
+		if (deadline === void 0) return yield* effect;
+		const selected = deadline;
+		return yield* effect.pipe(Effect.timeoutOrElse({
+			duration: Duration.millis(selected.remaining),
+			orElse: () => Clock.currentTimeMillis.pipe(Effect.flatMap((timeoutAt) => Effect.fail(durationExceeded(selected.node, timeoutAt))))
+		}));
+	});
+	const child = Effect.fn("UsageBudgetNode.child")(function* (childConfig) {
+		const childKey = `${key}/${nodeKeyComponent(childConfig)}`;
+		const childHandleId = Symbol(`usage-budget:${childConfig.level}:${childConfig.id}`);
+		const now = yield* Clock.currentTimeMillis;
+		const registration = yield* Ref.modify(ledger, (state) => {
+			if (liveHierarchy(state) === void 0) return [{ _tag: "retired" }, state];
+			if (levelOrder[childConfig.level] <= levelOrder[config.level]) return [{
+				_tag: "invalid",
+				error: InvalidBudgetHierarchy.make({
+					parentLevel: config.level,
+					childLevel: childConfig.level
+				})
+			}, state];
+			const existing = state.nodes.get(childKey);
+			if (existing !== void 0) return sameLimits(existing.config.limits, childConfig.limits) ? [{ _tag: "success" }, { nodes: new Map(state.nodes).set(childKey, {
+				...existing,
+				handles: new Set(existing.handles).add(childHandleId)
+			}) }] : [{
+				_tag: "conflict",
+				error: BudgetNodeConflict.make({
+					scopeLevel: childConfig.level,
+					scopeId: childConfig.id
+				})
+			}, state];
+			return [{ _tag: "success" }, { nodes: new Map(state.nodes).set(childKey, {
+				config: childConfig,
+				startedAt: now,
+				totals: emptyTotals(),
+				handles: /* @__PURE__ */ new Set([childHandleId])
+			}) }];
+		});
+		if (registration._tag === "retired") return yield* retiredDefect();
+		if (registration._tag === "conflict" || registration._tag === "invalid") return yield* registration.error;
+		return makeNode(ledger, childKey, hierarchy, childConfig, childHandleId);
+	});
+	const retire = Effect.uninterruptible(Ref.update(ledger, (state) => {
+		const existing = state.nodes.get(key);
+		if (existing === void 0 || !existing.handles.has(handleId)) return state;
+		const handles = new Set(existing.handles);
+		handles.delete(handleId);
+		const nodes = new Map(state.nodes).set(key, {
+			...existing,
+			handles
+		});
+		return { nodes: pruneRetiredHierarchy(nodes, hierarchy) };
+	}));
+	return {
+		level: config.level,
+		id: config.id,
+		child,
+		childScoped: (childConfig) => Effect.acquireRelease(child(childConfig), (node) => node.retire),
+		retire,
+		consume: (delta) => Clock.currentTimeMillis.pipe(Effect.flatMap((now) => Ref.modify(ledger, (state) => {
+			if (liveHierarchy(state) === void 0) return [{ _tag: "retired" }, state];
+			const updates = /* @__PURE__ */ new Map();
+			for (const ancestorKey of hierarchy) {
+				const node = state.nodes.get(ancestorKey);
+				if (node === void 0) return [{ _tag: "retired" }, state];
+				const totals = addUsage(node, delta, now);
+				const error = exceeded(node, totals);
+				if (error !== void 0) return [{
+					_tag: "failure",
+					error
+				}, state];
+				updates.set(ancestorKey, {
+					...node,
+					totals
+				});
+			}
+			const nextNodes = new Map(state.nodes);
+			for (const [updatedKey, updatedNode] of updates) nextNodes.set(updatedKey, updatedNode);
+			const value = updates.get(key)?.totals;
+			return value === void 0 ? [{ _tag: "retired" }, state] : [{
+				_tag: "success",
+				value
+			}, { nodes: nextNodes }];
+		}).pipe(Effect.flatMap((result) => {
+			switch (result._tag) {
+				case "success": return Effect.succeed(result.value);
+				case "failure": return Effect.fail(result.error);
+				case "retired": return retiredDefect();
+			}
+		})))),
+		snapshot,
+		guard
+	};
+};
+/** Create the outermost node of a hierarchy. Child nodes share its atomic ledger. */
+const makeUsageBudgetRoot = Effect.fn("makeUsageBudgetRoot")(function* (config) {
+	const startedAt = yield* Clock.currentTimeMillis;
+	const key = nodeKeyComponent(config);
+	const handleId = Symbol(`usage-budget:${config.level}:${config.id}`);
+	const ledger = yield* Ref.make({ nodes: /* @__PURE__ */ new Map([[key, {
+		config,
+		startedAt,
+		totals: emptyTotals(),
+		handles: /* @__PURE__ */ new Set([handleId])
+	}]]) });
+	return makeNode(ledger, key, [], config, handleId);
+});
+/** Compatibility constructor for a standalone Run budget. */
+const makeUsageBudget = (limits) => makeUsageBudgetRoot(UsageBudgetNodeConfig.make({
+	level: "run",
+	id: "standalone-run",
+	limits
+}));
+//#endregion
+export { BudgetExceeded, BudgetNodeConflict, InvalidBudgetHierarchy, UsageBudgetLimits, UsageBudgetNodeConfig, UsageDelta, UsageTotals, makeUsageBudget, makeUsageBudgetRoot, Budget_exports as t };
+
+//# sourceMappingURL=Budget.mjs.map

package/dist/capabilities/Budget.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Budget.mjs","names":[],"sources":["../../src/capabilities/Budget.ts"],"sourcesContent":["import { Clock, Duration, Effect, Ref, Schema, type Scope } from \"effect\";\n\nconst Natural = Schema.Natural;\nconst BudgetLevel = Schema.Literals([\"global\", \"tenant\", \"agent\", \"thread\", \"run\"]);\n\nexport type BudgetLevel = typeof BudgetLevel.Type;\n\n/** Fixed units avoid floating-point currency accounting: costs are micro-USD. */\nexport class UsageTotals extends Schema.Class<UsageTotals>(\n  \"@effect-agent/capabilities/UsageTotals\",\n)({\n  /** Total input tokens across every model call, INCLUDING cache reads and writes at par. */\n  inputTokens: Natural,\n  outputTokens: Natural,\n  /** Informational split of `inputTokens` served from the provider prompt cache; never separately limited. */\n  cacheReadInputTokens: Natural,\n  /** Informational split of `inputTokens` written to the provider prompt cache; never separately limited. */\n  cacheWriteInputTokens: Natural,\n  /** The most recent model call's input tokens — the live model-context estimate (CAP-017). */\n  lastInputTokens: Natural,\n  /** The most recent model call's output tokens. */\n  lastOutputTokens: Natural,\n  toolCalls: Natural,\n  costMicrousd: Natural,\n  elapsedMillis: Natural,\n}) {}\n\n/** Increment recorded at one model/tool accounting boundary. */\nexport class UsageDelta extends Schema.Class<UsageDelta>(\"@effect-agent/capabilities/UsageDelta\")({\n  /** `1` for a model-response boundary, `0` for a mid-pass tool charge; gates last-call tracking. */\n  modelCalls: Natural,\n  /** Total input tokens of this boundary, INCLUDING cache reads and writes at par. */\n  inputTokens: Natural,\n  outputTokens: Natural,\n  /** Informational split of `inputTokens` served from the provider prompt cache; never separately limited. */\n  cacheReadInputTokens: Natural,\n  /** Informational split of `inputTokens` written to the provider prompt cache; never separately limited. */\n  cacheWriteInputTokens: Natural,\n  toolCalls: Natural,\n  costMicrousd: Natural,\n}) {}\n\n/** All optional limits are finite when present; absent means not configured. */\nexport class UsageBudgetLimits extends Schema.Class<UsageBudgetLimits>(\n  \"@effect-agent/capabilities/UsageBudgetLimits\",\n)({\n  maxInputTokens: Schema.optionalKey(Natural),\n  maxOutputTokens: Schema.optionalKey(Natural),\n  maxToolCalls: Schema.optionalKey(Natural),\n  maxCostMicrousd: Schema.optionalKey(Natural),\n  maxDurationMillis: Schema.optionalKey(Natural),\n}) {}\n\n/** Identity and local limits for one node in a global-to-Run budget hierarchy. */\nexport class UsageBudgetNodeConfig extends Schema.Class<UsageBudgetNodeConfig>(\n  \"@effect-agent/capabilities/UsageBudgetNodeConfig\",\n)({\n  level: BudgetLevel,\n  id: Schema.NonEmptyString,\n  limits: UsageBudgetLimits,\n}) {}\n\n/** Typed finite-budget rejection. A rejected increment is not committed at any hierarchy level. */\nexport class BudgetExceeded extends Schema.TaggedError<BudgetExceeded>()(\"BudgetExceeded\", {\n  scopeLevel: BudgetLevel,\n  scopeId: Schema.NonEmptyString,\n  limit: Schema.Literals([\"input-tokens\", \"output-tokens\", \"tool-calls\", \"cost\", \"duration\"]),\n  limitValue: Natural,\n  observedValue: Natural,\n}) {}\n\n/** Hierarchical accounting authority. All ancestors share one atomic Ref-backed transaction. */\nexport interface UsageBudgetNode {\n  readonly level: BudgetLevel;\n  readonly id: string;\n  /**\n   * Register or re-attach one child node. Re-attaching an already-registered\n   * `level:id` with identical limits returns a handle to the shared\n   * registration; different limits fail with BudgetNodeConflict rather than\n   * being silently ignored. Every returned handle owns one registration and\n   * must be retired when its lifetime ends; prefer `childScoped` when the\n   * lifetime already belongs to an Effect Scope.\n   */\n  readonly child: (\n    config: UsageBudgetNodeConfig,\n  ) => Effect.Effect<UsageBudgetNode, InvalidBudgetHierarchy | BudgetNodeConflict>;\n  /** Register a child whose registration is retired when the current Scope closes. */\n  readonly childScoped: (\n    config: UsageBudgetNodeConfig,\n  ) => Effect.Effect<UsageBudgetNode, InvalidBudgetHierarchy | BudgetNodeConflict, Scope.Scope>;\n  /**\n   * Release this handle's registration exactly once. Accumulated usage stays\n   * charged to every live ancestor; a node is reclaimed only after its last\n   * handle and every descendant have retired.\n   */\n  readonly retire: Effect.Effect<void>;\n  readonly consume: (delta: UsageDelta) => Effect.Effect<UsageTotals, BudgetExceeded>;\n  readonly snapshot: Effect.Effect<UsageTotals>;\n  /**\n   * Guard stalled model/tool work with the earliest configured ancestor deadline.\n   * The timeout is driven by Effect Clock and interrupts the guarded child effect.\n   */\n  readonly guard: <A, E, R>(\n    effect: Effect.Effect<A, E, R>,\n  ) => Effect.Effect<A, E | BudgetExceeded, R>;\n}\n\n/** A child budget must move strictly inward through the declared hierarchy. */\nexport class InvalidBudgetHierarchy extends Schema.TaggedError<InvalidBudgetHierarchy>()(\n  \"InvalidBudgetHierarchy\",\n  {\n    parentLevel: BudgetLevel,\n    childLevel: BudgetLevel,\n  },\n) {}\n\n/** A child `level:id` is already registered with different limits; neither set may win silently. */\nexport class BudgetNodeConflict extends Schema.TaggedError<BudgetNodeConflict>()(\n  \"BudgetNodeConflict\",\n  {\n    scopeLevel: BudgetLevel,\n    scopeId: Schema.NonEmptyString,\n  },\n) {}\n\ninterface LedgerNode {\n  readonly config: UsageBudgetNodeConfig;\n  readonly startedAt: number;\n  readonly totals: UsageTotals;\n  /** Ledger-owned identities of the live handles for this exact registration. */\n  readonly handles: ReadonlySet<symbol>;\n}\n\ninterface BudgetLedger {\n  readonly nodes: ReadonlyMap<string, LedgerNode>;\n}\n\ntype ConsumptionResult =\n  | { readonly _tag: \"success\"; readonly value: UsageTotals }\n  | { readonly _tag: \"failure\"; readonly error: BudgetExceeded }\n  | { readonly _tag: \"retired\" };\n\ntype ChildRegistrationResult =\n  | { readonly _tag: \"success\" }\n  | { readonly _tag: \"conflict\"; readonly error: BudgetNodeConflict }\n  | { readonly _tag: \"invalid\"; readonly error: InvalidBudgetHierarchy }\n  | { readonly _tag: \"retired\" };\n\nconst levelOrder: Readonly<Record<BudgetLevel, number>> = {\n  global: 0,\n  tenant: 1,\n  agent: 2,\n  thread: 3,\n  run: 4,\n};\n\nconst emptyTotals = (elapsedMillis = 0): UsageTotals =>\n  UsageTotals.make({\n    inputTokens: 0,\n    outputTokens: 0,\n    cacheReadInputTokens: 0,\n    cacheWriteInputTokens: 0,\n    lastInputTokens: 0,\n    lastOutputTokens: 0,\n    toolCalls: 0,\n    costMicrousd: 0,\n    elapsedMillis,\n  });\n\n// Spread-preserve every accumulated field so future additions cannot be\n// silently dropped by an elapsed-only snapshot.\nconst withElapsed = (node: LedgerNode, now: number): UsageTotals =>\n  UsageTotals.make({\n    ...node.totals,\n    elapsedMillis: Math.max(0, now - node.startedAt),\n  });\n\nconst addUsage = (node: LedgerNode, delta: UsageDelta, now: number): UsageTotals =>\n  UsageTotals.make({\n    inputTokens: node.totals.inputTokens + delta.inputTokens,\n    outputTokens: node.totals.outputTokens + delta.outputTokens,\n    cacheReadInputTokens: node.totals.cacheReadInputTokens + delta.cacheReadInputTokens,\n    cacheWriteInputTokens: node.totals.cacheWriteInputTokens + delta.cacheWriteInputTokens,\n    lastInputTokens: delta.modelCalls > 0 ? delta.inputTokens : node.totals.lastInputTokens,\n    lastOutputTokens: delta.modelCalls > 0 ? delta.outputTokens : node.totals.lastOutputTokens,\n    toolCalls: node.totals.toolCalls + delta.toolCalls,\n    costMicrousd: node.totals.costMicrousd + delta.costMicrousd,\n    elapsedMillis: Math.max(0, now - node.startedAt),\n  });\n\nconst exceeded = (node: LedgerNode, totals: UsageTotals): BudgetExceeded | undefined => {\n  const limits = node.config.limits;\n\n  const checks: ReadonlyArray<readonly [BudgetExceeded[\"limit\"], number | undefined, number]> = [\n    [\"input-tokens\", limits.maxInputTokens, totals.inputTokens],\n    [\"output-tokens\", limits.maxOutputTokens, totals.outputTokens],\n    [\"tool-calls\", limits.maxToolCalls, totals.toolCalls],\n    [\"cost\", limits.maxCostMicrousd, totals.costMicrousd],\n    [\"duration\", limits.maxDurationMillis, totals.elapsedMillis],\n  ];\n\n  for (const [limit, limitValue, observedValue] of checks) {\n    if (limitValue !== undefined && observedValue > limitValue) {\n      return BudgetExceeded.make({\n        scopeLevel: node.config.level,\n        scopeId: node.config.id,\n        limit,\n        limitValue,\n        observedValue,\n      });\n    }\n  }\n\n  return undefined;\n};\n\nconst sameLimits = (a: UsageBudgetLimits, b: UsageBudgetLimits): boolean =>\n  a.maxInputTokens === b.maxInputTokens &&\n  a.maxOutputTokens === b.maxOutputTokens &&\n  a.maxToolCalls === b.maxToolCalls &&\n  a.maxCostMicrousd === b.maxCostMicrousd &&\n  a.maxDurationMillis === b.maxDurationMillis;\n\n// JSON escapes lone surrogates before URI encoding; every valid string stays distinct,\n// and an ID can never introduce the path separator used by retirement.\nconst nodeKeyComponent = (config: UsageBudgetNodeConfig): string =>\n  `${config.level}:${encodeURIComponent(JSON.stringify(config.id))}`;\n\nconst durationExceeded = (node: LedgerNode, now: number): BudgetExceeded => {\n  const limitValue = node.config.limits.maxDurationMillis ?? 0;\n\n  return BudgetExceeded.make({\n    scopeLevel: node.config.level,\n    scopeId: node.config.id,\n    limit: \"duration\",\n    limitValue,\n    observedValue: Math.max(limitValue + 1, now - node.startedAt),\n  });\n};\n\n/** Reclaim one released leaf and any newly unowned ancestors on its fixed hierarchy path. */\nconst pruneRetiredHierarchy = (\n  nodes: Map<string, LedgerNode>,\n  hierarchy: ReadonlyArray<string>,\n): Map<string, LedgerNode> => {\n  for (let index = hierarchy.length - 1; index >= 0; index -= 1) {\n    const candidateKey = hierarchy[index];\n\n    if (candidateKey === undefined) continue;\n    const candidate = nodes.get(candidateKey);\n\n    if (candidate === undefined) continue;\n    if (candidate.handles.size > 0) break;\n    const childPrefix = `${candidateKey}/`;\n\n    if ([...nodes.keys()].some((otherKey) => otherKey.startsWith(childPrefix))) {\n      break;\n    }\n    nodes.delete(candidateKey);\n  }\n\n  return nodes;\n};\n\nconst makeNode = (\n  ledger: Ref.Ref<BudgetLedger>,\n  key: string,\n  ancestors: ReadonlyArray<string>,\n  config: UsageBudgetNodeConfig,\n  handleId: symbol,\n): UsageBudgetNode => {\n  const hierarchy = [...ancestors, key];\n\n  const retiredDefect = () =>\n    Effect.die(\n      new Error(`Usage budget handle ${config.level}:${config.id} was used after retirement`),\n    );\n\n  const liveHierarchy = (state: BudgetLedger): ReadonlyArray<LedgerNode> | undefined => {\n    const current = state.nodes.get(key);\n\n    if (current === undefined || !current.handles.has(handleId)) return undefined;\n    const nodes: Array<LedgerNode> = [];\n\n    for (const ancestorKey of hierarchy) {\n      const node = state.nodes.get(ancestorKey);\n\n      if (node === undefined) return undefined;\n      nodes.push(node);\n    }\n\n    return nodes;\n  };\n\n  const readLiveHierarchy = Ref.modify(\n    ledger,\n    (state): readonly [ReadonlyArray<LedgerNode> | undefined, BudgetLedger] => [\n      liveHierarchy(state),\n      state,\n    ],\n  );\n\n  const snapshot = Effect.gen(function* () {\n    const now = yield* Clock.currentTimeMillis;\n    const nodes = yield* readLiveHierarchy;\n\n    if (nodes === undefined) return yield* retiredDefect();\n    const node = nodes[nodes.length - 1];\n\n    if (node === undefined) return yield* retiredDefect();\n\n    return withElapsed(node, now);\n  });\n\n  const guard = <A, E, R>(\n    effect: Effect.Effect<A, E, R>,\n  ): Effect.Effect<A, E | BudgetExceeded, R> =>\n    Effect.gen(function* () {\n      const now = yield* Clock.currentTimeMillis;\n      const nodes = yield* readLiveHierarchy;\n\n      if (nodes === undefined) return yield* retiredDefect();\n      let deadline: { readonly remaining: number; readonly node: LedgerNode } | undefined;\n\n      for (const node of nodes) {\n        const current = withElapsed(node, now);\n        const alreadyExceeded = exceeded(node, current);\n\n        if (alreadyExceeded !== undefined) {\n          return yield* alreadyExceeded;\n        }\n        const maxDuration = node.config.limits.maxDurationMillis;\n\n        if (maxDuration !== undefined) {\n          const remaining = maxDuration - current.elapsedMillis;\n\n          if (remaining <= 0) {\n            return yield* durationExceeded(node, now);\n          }\n          if (deadline === undefined || remaining < deadline.remaining) {\n            deadline = { remaining, node };\n          }\n        }\n      }\n      if (deadline === undefined) {\n        return yield* effect;\n      }\n      const selected = deadline;\n\n      return yield* effect.pipe(\n        Effect.timeoutOrElse({\n          duration: Duration.millis(selected.remaining),\n          orElse: () =>\n            Clock.currentTimeMillis.pipe(\n              Effect.flatMap((timeoutAt) =>\n                Effect.fail(durationExceeded(selected.node, timeoutAt)),\n              ),\n            ),\n        }),\n      );\n    });\n\n  const child = Effect.fn(\"UsageBudgetNode.child\")(function* (childConfig: UsageBudgetNodeConfig) {\n    const childKey = `${key}/${nodeKeyComponent(childConfig)}`;\n    const childHandleId = Symbol(`usage-budget:${childConfig.level}:${childConfig.id}`);\n    const now = yield* Clock.currentTimeMillis;\n\n    const registration = yield* Ref.modify(\n      ledger,\n      (state): readonly [ChildRegistrationResult, BudgetLedger] => {\n        if (liveHierarchy(state) === undefined) {\n          return [{ _tag: \"retired\" }, state];\n        }\n        if (levelOrder[childConfig.level] <= levelOrder[config.level]) {\n          return [\n            {\n              _tag: \"invalid\",\n              error: InvalidBudgetHierarchy.make({\n                parentLevel: config.level,\n                childLevel: childConfig.level,\n              }),\n            },\n            state,\n          ];\n        }\n        const existing = state.nodes.get(childKey);\n\n        if (existing !== undefined) {\n          return sameLimits(existing.config.limits, childConfig.limits)\n            ? [\n                { _tag: \"success\" },\n                {\n                  nodes: new Map(state.nodes).set(childKey, {\n                    ...existing,\n                    handles: new Set(existing.handles).add(childHandleId),\n                  }),\n                },\n              ]\n            : [\n                {\n                  _tag: \"conflict\",\n                  error: BudgetNodeConflict.make({\n                    scopeLevel: childConfig.level,\n                    scopeId: childConfig.id,\n                  }),\n                },\n                state,\n              ];\n        }\n\n        return [\n          { _tag: \"success\" },\n          {\n            nodes: new Map(state.nodes).set(childKey, {\n              config: childConfig,\n              startedAt: now,\n              totals: emptyTotals(),\n              handles: new Set([childHandleId]),\n            }),\n          },\n        ];\n      },\n    );\n\n    if (registration._tag === \"retired\") return yield* retiredDefect();\n    if (registration._tag === \"conflict\" || registration._tag === \"invalid\") {\n      return yield* registration.error;\n    }\n\n    return makeNode(ledger, childKey, hierarchy, childConfig, childHandleId);\n  });\n\n  const retire = Effect.uninterruptible(\n    Ref.update(ledger, (state) => {\n      const existing = state.nodes.get(key);\n\n      if (existing === undefined || !existing.handles.has(handleId)) return state;\n      const handles = new Set(existing.handles);\n\n      handles.delete(handleId);\n      const nodes = new Map(state.nodes).set(key, { ...existing, handles });\n\n      return { nodes: pruneRetiredHierarchy(nodes, hierarchy) };\n    }),\n  );\n\n  return {\n    level: config.level,\n    id: config.id,\n    child,\n    childScoped: (childConfig) => Effect.acquireRelease(child(childConfig), (node) => node.retire),\n    retire,\n    consume: (delta) =>\n      Clock.currentTimeMillis.pipe(\n        Effect.flatMap((now) =>\n          Ref.modify(ledger, (state): readonly [ConsumptionResult, BudgetLedger] => {\n            if (liveHierarchy(state) === undefined) {\n              return [{ _tag: \"retired\" }, state];\n            }\n            const updates = new Map<string, LedgerNode>();\n\n            for (const ancestorKey of hierarchy) {\n              const node = state.nodes.get(ancestorKey);\n\n              if (node === undefined) return [{ _tag: \"retired\" }, state];\n              const totals = addUsage(node, delta, now);\n              const error = exceeded(node, totals);\n\n              if (error !== undefined) {\n                return [{ _tag: \"failure\", error }, state];\n              }\n              updates.set(ancestorKey, { ...node, totals });\n            }\n            const nextNodes = new Map(state.nodes);\n\n            for (const [updatedKey, updatedNode] of updates) {\n              nextNodes.set(updatedKey, updatedNode);\n            }\n            const value = updates.get(key)?.totals;\n\n            return value === undefined\n              ? [{ _tag: \"retired\" }, state]\n              : [{ _tag: \"success\", value }, { nodes: nextNodes }];\n          }).pipe(\n            Effect.flatMap((result) => {\n              switch (result._tag) {\n                case \"success\":\n                  return Effect.succeed(result.value);\n                case \"failure\":\n                  return Effect.fail(result.error);\n                case \"retired\":\n                  return retiredDefect();\n              }\n            }),\n          ),\n        ),\n      ),\n    snapshot,\n    guard,\n  };\n};\n\n/** Create the outermost node of a hierarchy. Child nodes share its atomic ledger. */\nexport const makeUsageBudgetRoot = Effect.fn(\"makeUsageBudgetRoot\")(function* (\n  config: UsageBudgetNodeConfig,\n) {\n  const startedAt = yield* Clock.currentTimeMillis;\n  const key = nodeKeyComponent(config);\n  const handleId = Symbol(`usage-budget:${config.level}:${config.id}`);\n\n  const ledger = yield* Ref.make<BudgetLedger>({\n    nodes: new Map([\n      [\n        key,\n        {\n          config,\n          startedAt,\n          totals: emptyTotals(),\n          handles: new Set([handleId]),\n        },\n      ],\n    ]),\n  });\n\n  return makeNode(ledger, key, [], config, handleId);\n});\n\n/** Compatibility constructor for a standalone Run budget. */\nexport const makeUsageBudget = (limits: UsageBudgetLimits): Effect.Effect<UsageBudgetNode> =>\n  makeUsageBudgetRoot(\n    UsageBudgetNodeConfig.make({\n      level: \"run\",\n      id: \"standalone-run\",\n      limits,\n    }),\n  );\n"],"mappings":"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"}

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. */
+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>;
+  }>>;
+}>;
+type CodeModePassReport = typeof CodeModePassReport.Type;
+/** Model-decoded Code Mode parameters: one async function expression. */
+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).
+ */
+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).
+ */
+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. */
+declare class CodeModeDescriptionError extends CodeModeDescriptionError_base {}
+/** The namespace-record shape accepted by `CodeMode.make`. */
+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.
+ */
+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. */
+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`.
+ */
+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. */
+type CodeModeTools<Name extends string> = { readonly [Key in Name]: CodeModeTool<Name>; };
+/** Construction requirements of the Code Mode handler Layer. */
+type CodeModeLayerRequirements<Namespaces extends CodeModeNamespaces, RedactionRequirements = never> = CodeExecutor | Exclude<RedactionRequirements, Scope.Scope> | Tool.HandlersFor<CodeModeSelectedRecord<Namespaces>> | Tool.HandlerServices<CodeModeSelectedTool<Namespaces>>;
+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.
+ */
+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 { CodeModeDefinition, CodeModeDescriptionError, CodeModeFailure, CodeModeLayerRequirements, CodeModeNamespaces, CodeModeOptions, CodeModeParameters, CodeModePassReport, CodeModeSelectedRecord, CodeModeSelectedTool, CodeModeSuccess, CodeModeTool, CodeModeTools, make, CodeMode_d_exports as t };
+//# sourceMappingURL=CodeMode.d.mts.map