@anvia/core 1.0.7 → 1.0.9

package/README.md

@@ -202,14 +202,27 @@ const result = await generateCompletion({
   prompt: "Summarize this incident.",
   retries: { maxAttempts: 3, initialDelayMs: 100, maxDelayMs: 1_000 },
   abortSignal: controller.signal,
-  providerOptions: { reasoning: { effort: "medium" } },
+  controls: { reasoningEffort: "medium" },
 });
 ```
 
-`providerOptions` contains a strict JSON object passed to an adapter. Runtime values such as
+Completion models can advertise typed, provider-neutral `controls`. Reasoning-capable adapters use
+the `reasoningEffort` select control, so supported values are inferred from the model returned by
+`completionModel()`. An Agent can set control defaults, and a generate or stream call can override
+them for that run:
+
+```ts
+const agent = new Agent({ model, controls: { reasoningEffort: "medium" } });
+await agent.generate({ prompt: "Solve this.", controls: { reasoningEffort: "high" } });
+```
+
+Omitting a control means “Default”: the Agent default applies when configured, otherwise the
+provider chooses. Invalid control names and values are rejected before the provider call.
+
+`providerOptions` remains the escape hatch for a strict JSON object passed to an adapter. Runtime values such as
 `undefined`, non-finite numbers, cycles, a top-level array, and class instances are rejected rather
 than coerced. Nested arrays are valid JSON. Canonical Anvia fields such as model, input,
-temperature, tools, dimensions, text, and voice take precedence over conflicting provider keys.
+temperature, tools, controls, dimensions, text, and voice take precedence over conflicting provider keys.
 Cancellation is forwarded to provider SDK calls and is never retried.
 
 ## Agents
@@ -649,6 +662,158 @@ Import `McpClient` and `McpClientGroup` from `@anvia/mcp`, connect them, and pas
 `servers` to `new Agent({ mcpServers })`. See the `@anvia/mcp` README for transport configuration,
 connection ownership, URL safety, and cleanup.
 
+## Evaluations
+
+Import evaluation APIs from `@anvia/core/evals`. A suite contains cases, a target, and one or more
+metrics. Required metric failures make a case fail; infrastructure or evaluation errors produce an
+`invalid` outcome.
+
+```ts
+import { contains, exactMatch, runEvalSuite } from "@anvia/core/evals";
+
+const result = await runEvalSuite({
+  name: "support answers",
+  cases: [
+    {
+      id: "refund-window",
+      input: "When can I request a refund?",
+      expected: "Refunds are available for 30 days.",
+    },
+  ],
+  target: async (input) => answerSupportQuestion(input),
+  metrics: [exactMatch(), contains({ expected: "30 days" })],
+});
+
+console.log(result.cases);
+console.log(result.results[0]?.scores.exact_match);
+```
+
+`runEvalSuite` infers the case input, target output, expected value, metric names, and score types.
+Metrics that implicitly read `case.expected`, `case.context`, or `case.retrievalContext` require
+those fields at compile time. Supplying an explicit metric value or selector removes the matching
+case requirement.
+
+### Built-in metrics
+
+Deterministic metrics do not call a model:
+
+- `exactMatch`, `contains`, `notContains`, `containsAll`, and `containsAny`
+- `matches`, `doesNotMatch`, `maxLength`, and `requiredFields`
+- `semanticSimilarity`, which uses an embedding model
+
+Judge metrics call a completion model and record their evaluation token usage:
+
+- `llmJudge` and `llmScore`
+- `answerRelevancy`, `promptAlignment`, `jsonCorrectness`, and `summarization`
+- `hallucination`, `faithfulness`, and `abstention`
+- `gEval`, `turnRelevancy`, and `knowledgeRetention`
+
+Numeric thresholds use values from `0` through `1`. `strictMode` requires a perfect higher-is-better
+score or a zero lower-is-better score. Judge metrics default to including a final explanation;
+setting `includeReason: false` saves that extra judge call when the explanation is unnecessary.
+
+### Typed custom metrics
+
+Use `createEvalTypes` to bind input, output, and expected types once when defining multiple custom
+metrics:
+
+```ts
+import { createEvalTypes, EvalOutcome } from "@anvia/core/evals";
+
+const supportEvals = createEvalTypes<string, { answer: string }, string>();
+
+const noHandoff = supportEvals.defineMetric({
+  name: "no_handoff",
+  dataType: "BOOLEAN",
+  evaluate: ({ output, signal }) =>
+    signal.aborted || output.answer.includes("contact support")
+      ? EvalOutcome.fail(false)
+      : EvalOutcome.pass(true),
+});
+```
+
+Custom metrics return `EvalOutcome.pass`, `EvalOutcome.fail`, or `EvalOutcome.invalid`. Thrown metric
+errors are converted to structured invalid outcomes containing the error kind and original error.
+
+### Execution controls
+
+Evaluation targets receive an optional third argument containing the case `AbortSignal`.
+
+```ts
+const result = await runEvalSuite({
+  // cases, target, and metrics...
+  name: "release gate",
+  cases,
+  target: async (input, testCase, context) =>
+    generateAnswer(input, { signal: context?.signal, metadata: testCase.metadata }),
+  metrics,
+  targetConcurrency: 4,
+  metricConcurrency: 2,
+  caseTimeoutMs: 30_000,
+  signal: deploymentSignal,
+  failFast: true,
+  caseIds: ["refund-window", "billing-owner"],
+  shard: { index: 0, count: 4 },
+  onProgress(event) {
+    console.log(event.type);
+  },
+});
+```
+
+- `concurrency` remains the shorthand for both target and metric concurrency.
+- `targetConcurrency` and `metricConcurrency` can limit them independently.
+- `caseTimeoutMs` covers the target and its metrics. Cooperative targets and metrics should observe
+  the supplied signal; the runner still stops awaiting work that ignores it.
+- Aborting the suite-level `signal` stops scheduling cases and rejects the run with the abort reason.
+- `caseIds`, `caseFilter`, and `shard` select cases before execution.
+- `failFast` throws `EvalFailFastError` after the first completed required failure or invalid case.
+- `onProgress` receives case, target, metric, and case-completion events.
+
+Use `selectEvalCaseIds(previousResult)` to select failed and invalid cases for a rerun.
+
+### Results, usage, and failures
+
+Every case result includes `targetStatus`, target and total durations, per-case usage and optional
+cost. Every metric result includes its duration, optional cost, outcome, and reporter errors. A
+successful target that returns `undefined` has `targetStatus: "succeeded"` and retains its `output`
+property, so it is distinct from a failed target.
+
+The suite aggregates metric totals, case totals, target and evaluation usage, costs, duration, and
+all reporter errors. Invalid outcomes may include these `kind` values: `target`, `metric`,
+`configuration`, `provider`, or `timeout`.
+
+### CI output and expectations
+
+`runEvalCli` prints a result and can set `process.exitCode`. Exit code `1` means a required metric
+failed; `2` means a required metric was invalid. Use `defineEvalExpectations` with a defined suite to
+type-check case and metric names.
+
+```ts
+import { defineEvalExpectations, defineEvalSuite, exactMatch, runEvalCli } from "@anvia/core/evals";
+
+const suite = defineEvalSuite({
+  name: "release gate",
+  cases: [{ id: "refund", input: "refund", expected: "30 days" }],
+  target: async () => "30 days",
+  metrics: [exactMatch({ name: "correct" })],
+});
+
+await runEvalCli({
+  ...suite,
+  expectations: defineEvalExpectations(suite, {
+    outcomes: { refund: { correct: "pass" } },
+  }),
+  exitCode: true,
+  maxValueLength: 2_000,
+  redact: (value, context) => (context.kind === "input" ? "[redacted]" : value),
+});
+```
+
+Use `formatEvalResult` for pure pretty or JSON formatting without writing to stdout. Both
+`formatEvalResult` and `runEvalCli` support value truncation and redaction. JSON output otherwise
+contains cases, outputs, metadata, and error details, so redact sensitive data before writing it to
+shared CI logs.
+
 ## Public Areas
 
 - `agent`: typed Agent runtime, retries, and stream events

package/dist/agent/index.d.ts

@@ -1,22 +1,22 @@
 export { M as ModelCallOptions } from '../model-call-options-CZkSw_xN.js';
 export { R as RetryContext, a as RetryOptions, b as RetrySetting } from '../retry-CjvSlKGW.js';
-export { A as Agent, a as AgentContextInput, b as AgentMemory, c as AgentMemoryOptions, d as AgentOptions, e as AgentToolInput, f as AgentToolOptions, C as CreateHybridVectorContextOptions, g as CreateVectorContextOptions, V as VectorContext, h as VectorContextBaseOptions, i as createVectorContext, j as isVectorContext } from '../agent-B-3jCRmI.js';
-import { M as Message, U as Usage, C as CompletionFinishReason } from '../types-DgvozfPc.js';
-import { A as AgentBlockedOutcome, g as AgentInteractionOutcome } from '../types-DL7wX6hJ.js';
-export { a as AgentChildStreamEvent, b as AgentDeltaEvent, c as AgentErrorEvent, d as AgentErrorStreamEvent, e as AgentFinishEvent, f as AgentInput, h as AgentLifecycle, i as AgentMemoryCompactionEvent, j as AgentMemoryCompactionOptions, k as AgentOutcome, l as AgentPrompt, m as AgentResponse, n as AgentRunOptions, o as AgentRunSettings, p as AgentStartEvent, q as AgentSteerInput, r as AgentSteerReceipt, s as AgentStepFinishEvent, t as AgentStream, u as AgentStreamEvent, v as AgentToolCallDeltaEvent, w as AgentToolFinishEvent, x as AgentToolStartEvent } from '../types-DL7wX6hJ.js';
+export { A as Agent, a as AgentContextInput, b as AgentMemory, c as AgentMemoryOptions, d as AgentOptions, e as AgentToolInput, f as AgentToolOptions, C as CreateHybridVectorContextOptions, g as CreateVectorContextOptions, V as VectorContext, h as VectorContextBaseOptions, i as createVectorContext, j as isVectorContext } from '../agent-DTmzs1Qr.js';
+import { M as Message, U as Usage, c as CompletionFinishReason } from '../types-CiHjqE6J.js';
+import { A as AgentBlockedOutcome, g as AgentInteractionOutcome } from '../types-CRda8x7p.js';
+export { a as AgentChildStreamEvent, b as AgentDeltaEvent, c as AgentErrorEvent, d as AgentErrorStreamEvent, e as AgentFinishEvent, f as AgentInput, h as AgentLifecycle, i as AgentMemoryCompactionEvent, j as AgentMemoryCompactionOptions, k as AgentOutcome, l as AgentPrompt, m as AgentResponse, n as AgentRunOptions, o as AgentRunSettings, p as AgentStartEvent, q as AgentSteerInput, r as AgentSteerReceipt, s as AgentStepFinishEvent, t as AgentStream, u as AgentStreamEvent, v as AgentToolCallDeltaEvent, w as AgentToolFinishEvent, x as AgentToolStartEvent } from '../types-CRda8x7p.js';
 import '../zod-schema-C7F4clpm.js';
 import 'zod';
-import '../types-DhkodEft.js';
+import '../types-h0EL6Xn0.js';
 import '../type-utils-CtHVDRn_.js';
-import '../types-DjqRHeAi.js';
-import '../tool-BpqpoRSE.js';
-import '../types-DmzRCbU5.js';
-import '../middleware-kcF8AusP.js';
+import '../types-DfRPfehE.js';
+import '../tool-DQMZpZSS.js';
+import '../types-CafU6Ux5.js';
+import '../middleware-mY_lpjDp.js';
 import './interactions/index.js';
-import '../types-DC1U1XwW.js';
-import '../dynamic-tools-aIZlg5x1.js';
+import '../types-C1xYKXF2.js';
+import '../dynamic-tools-CNHSPXr1.js';
 import '../types-Cr4uiYo5.js';
-import '../types-CXNE592e.js';
+import '../types-CODGMHnp.js';
 
 type AgentStructuredOutputPhase = "truncated" | "content-filter" | "parse" | "schema";
 type AgentStructuredOutputFormat = "raw" | "json-fence" | "unlabeled-fence";

package/dist/agent/index.js

@@ -2,11 +2,11 @@ import {
   Agent,
   createVectorContext,
   isVectorContext
-} from "../chunk-HNRNTFMQ.js";
+} from "../chunk-GAOZ263Y.js";
 import "../chunk-OJBFDBLG.js";
 import "../chunk-J6LVLV6P.js";
-import "../chunk-XMVOBX43.js";
-import "../chunk-34EDX4ZL.js";
+import "../chunk-JLJMVRRE.js";
+import "../chunk-Q5BCNYED.js";
 import "../chunk-KSKST3KP.js";
 import "../chunk-YK4WAAS4.js";
 import "../chunk-2QZJTG2E.js";
@@ -22,8 +22,8 @@ import {
 } from "../chunk-AHLKV6KP.js";
 import "../chunk-K5L7R7XM.js";
 import "../chunk-IZNOP6JG.js";
-import "../chunk-D4PACGPA.js";
-import "../chunk-TB5EKZM7.js";
+import "../chunk-4UQALF5Y.js";
+import "../chunk-OI3LSMJG.js";
 import "../chunk-7JLAIN6E.js";
 import "../chunk-QGX73TSQ.js";
 import "../chunk-3XQGVDU5.js";

package/dist/agent/interactions/index.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { p as JsonValue, J as JsonObject, $ as ToolQuestionAnswer } from '../../types-DgvozfPc.js';
+import { t as JsonValue, J as JsonObject, a4 as ToolQuestionAnswer } from '../../types-CiHjqE6J.js';
 import '../../model-call-options-CZkSw_xN.js';
 
 type AgentQuestionChoice = Readonly<{

package/dist/{agent-B-3jCRmI.d.ts → agent-DTmzs1Qr.d.ts}

@@ -1,17 +1,17 @@
 import { b as RetrySetting } from './retry-CjvSlKGW.js';
-import { D as Document, c as CompletionModel, P as ProviderTool, J as JsonObject, v as ToolChoice } from './types-DgvozfPc.js';
+import { D as Document, d as CompletionModel, P as ProviderTool, J as JsonObject, C as CompletionControlValues, f as CompletionModelControlsOf, z as ToolChoice } from './types-CiHjqE6J.js';
 import { Z as ZodSchema } from './zod-schema-C7F4clpm.js';
-import { d as GuardrailPolicyInput, c as GuardrailPolicy } from './types-DhkodEft.js';
-import { a as McpServer } from './types-DjqRHeAi.js';
-import { E as MemoryStore, z as MemorySavePolicy, F as MemoryTokenCounter, n as MemoryCompactor, d as MemoryCompactionConflictRetryOptions, y as MemoryOptions, k as MemoryCompactionResult } from './types-DmzRCbU5.js';
-import { h as AgentLifecycle, F as AgentObservabilityOptions, n as AgentRunOptions, k as AgentOutcome, o as AgentRunSettings, t as AgentStream, j as AgentMemoryCompactionOptions } from './types-DL7wX6hJ.js';
-import { A as AgentMiddleware } from './middleware-kcF8AusP.js';
-import { A as AnyTool, T as Tool, c as ToolCallContext, N as NormalizedToolOutput } from './tool-BpqpoRSE.js';
+import { d as GuardrailPolicyInput, c as GuardrailPolicy } from './types-h0EL6Xn0.js';
+import { a as McpServer } from './types-DfRPfehE.js';
+import { E as MemoryStore, z as MemorySavePolicy, F as MemoryTokenCounter, n as MemoryCompactor, d as MemoryCompactionConflictRetryOptions, y as MemoryOptions, k as MemoryCompactionResult } from './types-CafU6Ux5.js';
+import { h as AgentLifecycle, F as AgentObservabilityOptions, n as AgentRunOptions, k as AgentOutcome, o as AgentRunSettings, t as AgentStream, j as AgentMemoryCompactionOptions } from './types-CRda8x7p.js';
+import { A as AgentMiddleware } from './middleware-mY_lpjDp.js';
+import { A as AnyTool, T as Tool, c as ToolCallContext, N as NormalizedToolOutput } from './tool-DQMZpZSS.js';
 import { AgentContinuation, AgentInteractionResponse } from './agent/interactions/index.js';
-import { a as SkillSet } from './types-DC1U1XwW.js';
-import { T as ToolIndex } from './dynamic-tools-aIZlg5x1.js';
+import { a as SkillSet } from './types-C1xYKXF2.js';
+import { T as ToolIndex } from './dynamic-tools-CNHSPXr1.js';
 import { E as EmbeddingModel, c as SparseEmbeddingModel } from './types-Cr4uiYo5.js';
-import { V as VectorFilter, a as VectorSearchResult, d as VectorStore, H as HybridVectorStore, e as VectorFusion } from './types-CXNE592e.js';
+import { V as VectorFilter, a as VectorSearchResult, d as VectorStore, H as HybridVectorStore, e as VectorFusion } from './types-CODGMHnp.js';
 
 type VectorContextBaseOptions<T = unknown> = {
     topK: number;
@@ -57,6 +57,7 @@ type AgentOptions<Output = string, M extends CompletionModel = CompletionModel,
     temperature?: number | undefined;
     maxTokens?: number | undefined;
     providerOptions?: JsonObject | undefined;
+    controls?: CompletionControlValues<CompletionModelControlsOf<M>> | undefined;
     retries?: RetrySetting | undefined;
     toolChoice?: ToolChoice | undefined;
     maxTurns?: number | undefined;
@@ -95,6 +96,7 @@ type ResolvedAgentOptions<Output = string, M extends CompletionModel = Completio
     temperature?: number | undefined;
     maxTokens?: number | undefined;
     providerOptions?: JsonObject | undefined;
+    controls?: CompletionControlValues<CompletionModelControlsOf<M>> | undefined;
     retries?: RetrySetting | undefined;
     tools?: readonly AnyTool[] | undefined;
     mcpServers?: readonly McpServer[] | undefined;
@@ -128,6 +130,7 @@ declare class Agent<Output = string, M extends CompletionModel = CompletionModel
     readonly temperature: number | undefined;
     readonly maxTokens: number | undefined;
     readonly providerOptions: JsonObject | undefined;
+    readonly controls: CompletionControlValues<CompletionModelControlsOf<M>> | undefined;
     readonly retries: RetrySetting | undefined;
     readonly mcpServers: readonly McpServer[];
     readonly tools: readonly AnyTool[];
@@ -140,9 +143,9 @@ declare class Agent<Output = string, M extends CompletionModel = CompletionModel
     readonly middlewares: readonly AgentMiddleware[];
     readonly memory: AgentMemory | undefined;
     constructor(options: AgentOptions<Output, M, ContextDocument>);
-    generate(options: AgentRunOptions<Output, RawResponseOf<M>>): Promise<AgentOutcome<Output>>;
-    resume(continuation: AgentContinuation, response: AgentInteractionResponse, settings?: AgentRunSettings<Output, RawResponseOf<M>>): Promise<AgentOutcome<Output>>;
-    stream(options: AgentRunOptions<Output, RawResponseOf<M>>): AgentStream<Output, RawResponseOf<M>>;
+    generate(options: AgentRunOptions<Output, RawResponseOf<M>, CompletionModelControlsOf<M>>): Promise<AgentOutcome<Output>>;
+    resume(continuation: AgentContinuation, response: AgentInteractionResponse, settings?: AgentRunSettings<Output, RawResponseOf<M>, CompletionModelControlsOf<M>>): Promise<AgentOutcome<Output>>;
+    stream(options: AgentRunOptions<Output, RawResponseOf<M>, CompletionModelControlsOf<M>>): AgentStream<Output, RawResponseOf<M>>;
     compactMemory(options: AgentMemoryCompactionOptions): Promise<MemoryCompactionResult>;
     asTool(options: AgentToolOptions): Tool<{
         prompt: string;

package/dist/chunk-4UQALF5Y.js

@@ -0,0 +1,117 @@
+// src/completion/controls.ts
+var REASONING_EFFORT_CONTROL_ID = "reasoningEffort";
+function defineCompletionModelControls(controls) {
+  if (typeof controls !== "object" || controls === null || Array.isArray(controls)) {
+    throw new TypeError("Completion model controls must be an object.");
+  }
+  const snapshot = {};
+  for (const [id, control] of Object.entries(controls)) {
+    if (id.trim().length === 0) {
+      throw new TypeError("Completion control ids must not be empty.");
+    }
+    if (typeof control !== "object" || control === null || Array.isArray(control)) {
+      throw new TypeError(`Completion control "${id}" must be an object.`);
+    }
+    if (control.type !== "select") {
+      throw new TypeError(`Completion control "${id}" must have type "select".`);
+    }
+    if (typeof control.label !== "string" || control.label.trim().length === 0) {
+      throw new TypeError(`Completion control "${id}" must have a non-empty label.`);
+    }
+    if (!Array.isArray(control.options) || control.options.length === 0) {
+      throw new TypeError(`Completion control "${id}" must declare at least one option.`);
+    }
+    const options = control.options.map((option) => {
+      if (typeof option !== "string" || option.trim().length === 0) {
+        throw new TypeError(`Completion control "${id}" options must not be empty.`);
+      }
+      return option;
+    });
+    if (new Set(options).size !== options.length) {
+      throw new TypeError(`Completion control "${id}" options must be unique.`);
+    }
+    if (control.defaultValue !== void 0 && (typeof control.defaultValue !== "string" || !options.includes(control.defaultValue))) {
+      throw new TypeError(
+        `Completion control "${id}" defaultValue must be one of its declared options.`
+      );
+    }
+    if (control.description !== void 0 && typeof control.description !== "string") {
+      throw new TypeError(`Completion control "${id}" description must be a string.`);
+    }
+    let next = {
+      type: "select",
+      label: control.label,
+      options: Object.freeze(options)
+    };
+    if (control.description !== void 0) {
+      next = { ...next, description: control.description };
+    }
+    if (control.defaultValue !== void 0) {
+      next = { ...next, defaultValue: control.defaultValue };
+    }
+    Object.defineProperty(snapshot, id, {
+      value: Object.freeze(next),
+      enumerable: true,
+      configurable: false,
+      writable: false
+    });
+  }
+  return Object.freeze(snapshot);
+}
+function mergeCompletionControlValues(defaults, overrides) {
+  if (defaults === void 0 && overrides === void 0) return void 0;
+  const values = {};
+  for (const source of [defaults, overrides]) {
+    for (const [id, value] of Object.entries(source ?? {})) {
+      if (typeof value !== "string") continue;
+      Object.defineProperty(values, id, {
+        value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+      });
+    }
+  }
+  return Object.keys(values).length === 0 ? void 0 : Object.freeze(values);
+}
+
+// src/completion/documents.ts
+function normalizeDocuments(documents) {
+  if (documents.length === 0) {
+    return void 0;
+  }
+  return { role: "user", content: documents.map(formatDocument).join("\n") };
+}
+function formatDocument(document) {
+  return `<file id: ${document.id}>
+${formatDocumentBody(document)}
+</file>
+`;
+}
+function formatDocumentBody(document) {
+  const metadata = formatMetadata(document.additionalProps);
+  return metadata === void 0 ? document.text : `${metadata}
+${document.text}`;
+}
+function formatMetadata(additionalProps) {
+  if (additionalProps === void 0) {
+    return void 0;
+  }
+  const entries = Object.entries(additionalProps).sort(
+    ([left], [right]) => left.localeCompare(right)
+  );
+  if (entries.length === 0) {
+    return void 0;
+  }
+  const metadata = entries.map(([key, value]) => `${key}: ${JSON.stringify(value)}`).join(" ");
+  return `<metadata ${metadata} />`;
+}
+
+export {
+  REASONING_EFFORT_CONTROL_ID,
+  defineCompletionModelControls,
+  mergeCompletionControlValues,
+  normalizeDocuments,
+  formatDocument
+};
+//# sourceMappingURL=chunk-4UQALF5Y.js.map

package/dist/chunk-4UQALF5Y.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/completion/controls.ts","../src/completion/documents.ts"],"sourcesContent":["import type {\n  CompletionControlValues,\n  CompletionModelControls,\n  CompletionModelSelectControl,\n} from \"./types\";\n\nexport const REASONING_EFFORT_CONTROL_ID = \"reasoningEffort\";\n\nexport type ReasoningEffortControls<Effort extends string = string> = Readonly<{\n  reasoningEffort: CompletionModelSelectControl<Effort>;\n}>;\n\nexport function defineCompletionModelControls<const Controls extends CompletionModelControls>(\n  controls: Controls,\n): Controls {\n  if (typeof controls !== \"object\" || controls === null || Array.isArray(controls)) {\n    throw new TypeError(\"Completion model controls must be an object.\");\n  }\n  const snapshot: Record<string, CompletionModelSelectControl> = {};\n  for (const [id, control] of Object.entries(controls)) {\n    if (id.trim().length === 0) {\n      throw new TypeError(\"Completion control ids must not be empty.\");\n    }\n    if (typeof control !== \"object\" || control === null || Array.isArray(control)) {\n      throw new TypeError(`Completion control \"${id}\" must be an object.`);\n    }\n    if (control.type !== \"select\") {\n      throw new TypeError(`Completion control \"${id}\" must have type \"select\".`);\n    }\n    if (typeof control.label !== \"string\" || control.label.trim().length === 0) {\n      throw new TypeError(`Completion control \"${id}\" must have a non-empty label.`);\n    }\n    if (!Array.isArray(control.options) || control.options.length === 0) {\n      throw new TypeError(`Completion control \"${id}\" must declare at least one option.`);\n    }\n    const options = control.options.map((option) => {\n      if (typeof option !== \"string\" || option.trim().length === 0) {\n        throw new TypeError(`Completion control \"${id}\" options must not be empty.`);\n      }\n      return option;\n    });\n    if (new Set(options).size !== options.length) {\n      throw new TypeError(`Completion control \"${id}\" options must be unique.`);\n    }\n    if (\n      control.defaultValue !== undefined &&\n      (typeof control.defaultValue !== \"string\" || !options.includes(control.defaultValue))\n    ) {\n      throw new TypeError(\n        `Completion control \"${id}\" defaultValue must be one of its declared options.`,\n      );\n    }\n    if (control.description !== undefined && typeof control.description !== \"string\") {\n      throw new TypeError(`Completion control \"${id}\" description must be a string.`);\n    }\n    let next: CompletionModelSelectControl = {\n      type: \"select\",\n      label: control.label,\n      options: Object.freeze(options),\n    };\n    if (control.description !== undefined) {\n      next = { ...next, description: control.description };\n    }\n    if (control.defaultValue !== undefined) {\n      next = { ...next, defaultValue: control.defaultValue };\n    }\n    Object.defineProperty(snapshot, id, {\n      value: Object.freeze(next),\n      enumerable: true,\n      configurable: false,\n      writable: false,\n    });\n  }\n  return Object.freeze(snapshot) as Controls;\n}\n\nexport function mergeCompletionControlValues<Controls extends CompletionModelControls>(\n  defaults: CompletionControlValues<Controls> | undefined,\n  overrides: CompletionControlValues<Controls> | undefined,\n): Readonly<Record<string, string>> | undefined {\n  if (defaults === undefined && overrides === undefined) return undefined;\n  const values: Record<string, string> = {};\n  for (const source of [defaults, overrides]) {\n    for (const [id, value] of Object.entries(source ?? {})) {\n      if (typeof value !== \"string\") continue;\n      Object.defineProperty(values, id, {\n        value,\n        enumerable: true,\n        configurable: true,\n        writable: true,\n      });\n    }\n  }\n  return Object.keys(values).length === 0 ? undefined : Object.freeze(values);\n}\n","import type { Document, Message } from \"./types\";\n\nexport function normalizeDocuments(documents: Document[]): Message | undefined {\n  if (documents.length === 0) {\n    return undefined;\n  }\n\n  return { role: \"user\", content: documents.map(formatDocument).join(\"\\n\") };\n}\n\nexport function formatDocument(document: Document): string {\n  return `<file id: ${document.id}>\\n${formatDocumentBody(document)}\\n</file>\\n`;\n}\n\nfunction formatDocumentBody(document: Document): string {\n  const metadata = formatMetadata(document.additionalProps);\n  return metadata === undefined ? document.text : `${metadata}\\n${document.text}`;\n}\n\nfunction formatMetadata(additionalProps: Record<string, string> | undefined): string | undefined {\n  if (additionalProps === undefined) {\n    return undefined;\n  }\n\n  const entries = Object.entries(additionalProps).sort(([left], [right]) =>\n    left.localeCompare(right),\n  );\n  if (entries.length === 0) {\n    return undefined;\n  }\n\n  const metadata = entries.map(([key, value]) => `${key}: ${JSON.stringify(value)}`).join(\" \");\n  return `<metadata ${metadata} />`;\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-HNRNTFMQ.js → chunk-GAOZ263Y.js}

@@ -13,10 +13,10 @@ import {
   createMemoryCompactionSummary,
   cumulativeCompactedMessageCount,
   resolveMemoryOptions
-} from "./chunk-XMVOBX43.js";
+} from "./chunk-JLJMVRRE.js";
 import {
   startAgentRunObservers
-} from "./chunk-34EDX4ZL.js";
+} from "./chunk-Q5BCNYED.js";
 import {
   isSkillTool
 } from "./chunk-YK4WAAS4.js";
@@ -50,9 +50,13 @@ import {
 import {
   mapWithConcurrency
 } from "./chunk-IZNOP6JG.js";
+import {
+  mergeCompletionControlValues
+} from "./chunk-4UQALF5Y.js";
 import {
   CompletionStreamAccumulator,
   Usage,
+  assertCompletionControlsSupported,
   assertCompletionRequestSupported,
   assertCompletionResponseIntegrity,
   createCompletionRequest,
@@ -60,7 +64,7 @@ import {
   isProviderTool,
   isStreamingCompletionModel,
   textFromAssistantContent
-} from "./chunk-TB5EKZM7.js";
+} from "./chunk-OI3LSMJG.js";
 import {
   assertJsonObject
 } from "./chunk-7JLAIN6E.js";
@@ -1957,6 +1961,7 @@ var AgentRun = class _AgentRun {
     const retrySetting = options.retries === void 0 ? agent.retries : options.retries;
     this.completionRetryOptions = retrySetting === void 0 || retrySetting === false ? void 0 : resolveRetryOptions(retrySetting);
     this.requestMiddlewares = [...options.middlewares ?? []];
+    this.controls = mergeCompletionControlValues(agent.controls, options.controls);
     this.memoryScope = options.memoryScope;
     this.memoryRecorder = new AgentRunMemory(agent, options.memoryScope, initialHistory);
     this.continuationState = options.continuationState;
@@ -1984,6 +1989,7 @@ var AgentRun = class _AgentRun {
   traceOptions;
   completionRetryOptions;
   requestMiddlewares;
+  controls;
   steeringMessages = [];
   runState = "idle";
   memoryRecorder;
@@ -2803,6 +2809,7 @@ var AgentRun = class _AgentRun {
       maxTokens: this.agent.maxTokens,
       providerOptions: this.agent.providerOptions,
       toolChoice: this.agent.toolChoice,
+      controls: this.controls,
       outputSchema: getAgentProviderOutputSchema(this.agent)
     });
     return this.runCompletionRequestMiddlewares(request, turn);
@@ -4341,6 +4348,7 @@ function resolveAgentOptions(options) {
     temperature: options.temperature,
     maxTokens: options.maxTokens,
     providerOptions: options.providerOptions,
+    controls: options.controls,
     retries: options.retries,
     tools: [...toolsByName.values()],
     mcpServers: [...options.mcpServers ?? []],
@@ -4681,6 +4689,7 @@ var Agent = class {
   temperature;
   maxTokens;
   providerOptions;
+  controls;
   retries;
   mcpServers;
   tools;
@@ -4706,6 +4715,8 @@ var Agent = class {
       assertJsonObject(resolved.providerOptions, "Agent providerOptions");
     }
     this.providerOptions = cloneFrozenPlainData(resolved.providerOptions);
+    assertCompletionControlsSupported(this.model, resolved.controls);
+    this.controls = cloneFrozenPlainData(resolved.controls);
     this.retries = cloneFrozenPlainData(resolved.retries);
     const preparedTools = prepareAgentTools(resolved);
     this.mcpServers = preparedTools.mcpServers;
@@ -4772,4 +4783,4 @@ export {
   markResolvedAgentOptions,
   Agent
 };
-//# sourceMappingURL=chunk-HNRNTFMQ.js.map
+//# sourceMappingURL=chunk-GAOZ263Y.js.map