@anvia/studio 1.0.11 → 1.0.13

package/README.md

@@ -120,16 +120,22 @@ new Studio([agent], {
 }).start();
 ```
 
-The playground message composer shows the allowed models for the selected agent. API callers can
-also select a model per run:
+The playground message composer shows the allowed models for the selected agent. It also renders
+generic selectors for controls advertised by each completion model and restores explicit choices
+from session metadata. “Default” omits the control, preserving Agent and provider defaults. API
+callers can select a model and controls per run:
 
 ```json
 {
+  "type": "messages",
   "messages": [{ "role": "user", "content": "Summarize this ticket" }],
   "model": {
     "providerId": "anthropic",
     "modelId": "claude-sonnet-4-20250514"
   },
+  "controls": {
+    "reasoningEffort": "high"
+  },
   "stream": true
 }
 ```

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { Hono } from 'hono';
 import { AgentObserver, AgentRunStartArgs, AgentRunObserver } from '@anvia/core/observability';
 import { AgentOutcome, AgentInteractionOutcome, AgentStreamEvent, Agent } from '@anvia/core/agent';
 import { AgentInteractionResponse } from '@anvia/core/agent/interactions';
-import { JsonObject, Message, JsonValue, CompletionModelCapabilities, ToolResultContentPart, Usage, CompletionModel, StreamingCompletionModel } from '@anvia/core/completion';
+import { JsonObject, Message, JsonValue, CompletionModelCapabilities, CompletionModelControls, ToolResultContentPart, Usage, CompletionModel, StreamingCompletionModel } from '@anvia/core/completion';
 import { MemoryStore, MemoryAppendOptions, MemoryErrorOptions, MemoryScope } from '@anvia/core/memory';
 import { ModelList } from '@anvia/core/model-listing';
 import { Pipeline, PipelineGraph } from '@anvia/core/pipeline';
@@ -68,6 +68,7 @@ type StudioModelSummary = StudioModelDefinition & {
     ref: string;
     providerId: string;
     providerName?: string;
+    controls?: CompletionModelControls;
 };
 type StudioModelProviderConfig = {
     id: string;
@@ -1038,6 +1039,7 @@ type AgentRunRequest = (AgentRunRequestBase & {
     maxTurns?: number;
     toolConcurrency?: number;
     model?: StudioModelRef;
+    controls?: Readonly<Record<string, string>>;
     interactionId?: never;
     response?: never;
 }) | (AgentRunRequestBase & {
@@ -1049,6 +1051,7 @@ type AgentRunRequest = (AgentRunRequestBase & {
     maxTurns?: never;
     toolConcurrency?: never;
     model?: never;
+    controls?: never;
 });
 type AgentRunResponse = Exclude<AgentOutcome, AgentInteractionOutcome> | Omit<AgentInteractionOutcome, "continuation" | "messages">;
 type AgentRunStreamEvent = AgentStreamEvent | StudioSessionLogEvent | StudioPipelineLogEvent | StudioPipelineFinalEvent;

package/dist/index.js

@@ -490,6 +490,8 @@ function generationMetadata(args, endArgs) {
     historyCount: request.chatHistory.length,
     temperature: request.temperature,
     maxTokens: request.maxTokens,
+    controls: request.controls,
+    reasoningEffort: request.controls?.reasoningEffort,
     toolChoice: request.toolChoice,
     providerOptionKeys: isRecord(request.providerOptions) ? Object.keys(request.providerOptions).sort() : void 0,
     hasOutputSchema: request.outputSchema !== void 0,
@@ -531,6 +533,8 @@ function completionRequestSummary(request) {
     toolNames: request.tools.map((tool) => tool.name),
     temperature: request.temperature,
     maxTokens: request.maxTokens,
+    controls: request.controls,
+    reasoningEffort: request.controls?.reasoningEffort,
     toolChoice: request.toolChoice,
     providerOptionKeys: isRecord(request.providerOptions) ? Object.keys(request.providerOptions).sort() : void 0,
     hasOutputSchema: request.outputSchema !== void 0
@@ -1026,7 +1030,12 @@ async function parseJsonBody(c, validate) {
 }
 
 // src/runtime/models.ts
+import {
+  assertCompletionControlsSupported,
+  CompletionCapabilityError
+} from "@anvia/core/completion";
 var STUDIO_MODEL_METADATA_KEY = "studioModel";
+var STUDIO_CONTROLS_METADATA_KEY = "studioControls";
 function createStudioModelRegistry(config) {
   if (config === void 0) {
     return void 0;
@@ -1073,7 +1082,7 @@ function studioModelsConfig(registry, agents) {
   }
   const providers = [...registry.providers.values()].map((provider) => {
     const models = [...provider.staticModels.values()].map(
-      (model) => modelSummary(provider, model.id, model)
+      (model) => staticModelSummary(provider, model.id, model)
     );
     const config2 = {
       id: provider.id,
@@ -1097,17 +1106,18 @@ function studioModelsConfig(registry, agents) {
 }
 function registerModelRoutes(app, props) {
   app.get("/models", async (c) => {
-    if (props.registry === void 0) {
+    const registry = props.registry;
+    if (registry === void 0) {
       return errorResponse(c, 404, "not_found", "Model registry not configured");
     }
     const providers = await Promise.all(
-      [...props.registry.providers.values()].map((provider) => providerCatalog(provider))
+      [...registry.providers.values()].map((provider) => providerCatalog(registry, provider))
     );
     const response = {
       providers
     };
-    if (props.registry.defaultModelRef !== void 0) {
-      response.defaultModelRef = props.registry.defaultModelRef;
+    if (registry.defaultModelRef !== void 0) {
+      response.defaultModelRef = registry.defaultModelRef;
     }
     return c.json(response);
   });
@@ -1119,7 +1129,7 @@ function registerModelRoutes(app, props) {
     if (provider === void 0) {
       return errorResponse(c, 404, "not_found", "Model provider not found");
     }
-    return c.json(await providerCatalog(provider));
+    return c.json(await providerCatalog(props.registry, provider));
   });
   app.get("/agents/:agentId/models", async (c) => {
     const agentId = c.req.param("agentId");
@@ -1155,6 +1165,14 @@ function resolveStudioModel(registry, input) {
     model = provider.createCompletionModel({ modelId });
     registry.modelCache.set(selectedRef, model);
   }
+  try {
+    assertCompletionControlsSupported(model, input.request.controls);
+  } catch (error) {
+    if (error instanceof CompletionCapabilityError) {
+      throw new ModelSelectionError(error.message);
+    }
+    throw error;
+  }
   const metadata = provider.staticModels.get(modelId);
   return {
     ref: selectedRef,
@@ -1166,6 +1184,16 @@ function sessionModelRef(metadata) {
   const value = metadata?.[STUDIO_MODEL_METADATA_KEY];
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 }
+function sessionControlValues(metadata) {
+  const value = metadata?.[STUDIO_CONTROLS_METADATA_KEY];
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const controls = Object.fromEntries(
+    Object.entries(value).filter(
+      (entry) => typeof entry[1] === "string"
+    )
+  );
+  return Object.freeze(controls);
+}
 function normalizeOptionalModelRef(ref) {
   return ref === void 0 ? void 0 : normalizeModelRef(ref);
 }
@@ -1190,7 +1218,9 @@ var ModelSelectionError = class extends Error {
 };
 async function agentModelsCatalog(registry, agent) {
   const policy = registry.agentPolicies.get(agent.id);
-  const catalogs = await Promise.all([...registry.providers.values()].map(providerCatalog));
+  const catalogs = await Promise.all(
+    [...registry.providers.values()].map((provider) => providerCatalog(registry, provider))
+  );
   const warnings = catalogs.flatMap(
     (catalog) => catalog.warning === void 0 ? [] : [{ providerId: catalog.id, warning: catalog.warning }]
   );
@@ -1205,7 +1235,7 @@ async function agentModelsCatalog(registry, agent) {
       const { providerId, modelId } = parseModelRef(ref);
       const provider = registry.providers.get(providerId);
       return provider === void 0 ? [] : [
-        modelSummary(provider, modelId, {
+        modelSummary(registry, provider, modelId, {
           id: modelId
         })
       ];
@@ -1216,16 +1246,33 @@ async function agentModelsCatalog(registry, agent) {
   const defaultModelRef = policy?.defaultModelRef ?? registry.defaultModelRef;
   const summary = {
     agentId: agent.id,
-    models: [...models, ...exactPolicyModels]
+    models: [...models, ...exactPolicyModels].map(
+      (model) => withAgentControlDefaults(model, agent.agent.controls)
+    )
   };
   if (defaultModelRef !== void 0) summary.defaultModelRef = defaultModelRef;
   if (warnings.length > 0) summary.warnings = warnings;
   return summary;
 }
-async function providerCatalog(provider) {
+function withAgentControlDefaults(model, defaults) {
+  if (model.controls === void 0 || defaults === void 0) return model;
+  let changed = false;
+  const controls = Object.fromEntries(
+    Object.entries(model.controls).map(([id, control]) => {
+      const defaultValue = defaults[id];
+      if (typeof defaultValue !== "string" || !control.options.includes(defaultValue) || control.defaultValue === defaultValue) {
+        return [id, control];
+      }
+      changed = true;
+      return [id, { ...control, defaultValue }];
+    })
+  );
+  return changed ? { ...model, controls } : model;
+}
+async function providerCatalog(registry, provider) {
   const models = /* @__PURE__ */ new Map();
   for (const model of provider.staticModels.values()) {
-    models.set(model.id, modelSummary(provider, model.id, model));
+    models.set(model.id, modelSummary(registry, provider, model.id, model));
   }
   let warning;
   if (provider.listModels !== void 0) {
@@ -1244,7 +1291,7 @@ async function providerCatalog(provider) {
         if (model.contextLength !== void 0) metadata.contextLength = model.contextLength;
         Object.assign(metadata, staticModel?.metadata);
         definition.metadata = metadata;
-        models.set(model.id, modelSummary(provider, model.id, definition));
+        models.set(model.id, modelSummary(registry, provider, model.id, definition));
       }
     } catch (error) {
       const serialized = serializeError(error);
@@ -1261,7 +1308,13 @@ async function providerCatalog(provider) {
   if (warning !== void 0) catalog.warning = warning;
   return catalog;
 }
-function modelSummary(provider, modelId, model) {
+function modelSummary(registry, provider, modelId, model) {
+  const summary = staticModelSummary(provider, modelId, model);
+  const controls = completionModelFor(registry, provider, modelId).controls;
+  if (controls !== void 0) summary.controls = controls;
+  return summary;
+}
+function staticModelSummary(provider, modelId, model) {
   const summary = {
     ...model,
     id: modelId,
@@ -1271,6 +1324,15 @@ function modelSummary(provider, modelId, model) {
   if (provider.name !== void 0) summary.providerName = provider.name;
   return summary;
 }
+function completionModelFor(registry, provider, modelId) {
+  const ref = `${provider.id}:${modelId}`;
+  let model = registry.modelCache.get(ref);
+  if (model === void 0) {
+    model = provider.createCompletionModel({ modelId });
+    registry.modelCache.set(ref, model);
+  }
+  return model;
+}
 function ensureModelAllowed(registry, agentId, ref) {
   const { providerId } = parseModelRef(ref);
   if (!registry.providers.has(providerId)) {
@@ -2469,13 +2531,13 @@ function parseRunRequestBody(c, body) {
     if (typeof body.interactionId !== "string" || body.interactionId.trim().length === 0) {
       return { error: errorResponse(c, 400, "bad_request", "interactionId must be a string") };
     }
-    if (body.messages !== void 0 || body.sessionId !== void 0 || body.model !== void 0) {
+    if (body.messages !== void 0 || body.sessionId !== void 0 || body.model !== void 0 || body.controls !== void 0) {
       return {
         error: errorResponse(
           c,
           400,
           "bad_request",
-          "Interaction responses cannot include messages, sessionId, or model"
+          "Interaction responses cannot include messages, sessionId, model, or controls"
         )
       };
     }
@@ -2578,6 +2640,14 @@ function parseRunRequestOptions(c, body, request) {
       };
     }
   }
+  if (request.type === "messages" && "controls" in body) {
+    if (!isObject(body.controls) || Object.values(body.controls).some((value) => typeof value !== "string")) {
+      return {
+        error: errorResponse(c, 400, "bad_request", "controls must be an object of string values")
+      };
+    }
+    request.controls = body.controls;
+  }
   if ("metadata" in body) {
     if (!isJsonObject(body.metadata)) {
       return { error: errorResponse(c, 400, "bad_request", "metadata must be an object") };
@@ -3195,29 +3265,35 @@ async function prepareAgentRun(c, props, abortSignal) {
   if (session instanceof Response) {
     return session;
   }
-  const selectedModel = selectRunModel(c, props, agent, body, session);
+  const persistedControls = sessionControlValues(session?.metadata);
+  const runBody = body.controls === void 0 && persistedControls !== void 0 ? { ...body, controls: persistedControls } : body;
+  const selectedModel = selectRunModel(c, props, agent, runBody, session);
   if (selectedModel instanceof Response) {
     return selectedModel;
   }
-  const runAgent = selectedModel.model === void 0 ? agent.agent : cloneAgent(agent.agent, { model: selectedModel.model });
+  const runAgent = selectedModel.model === void 0 ? agent.agent : cloneAgent(agent.agent, {
+    model: selectedModel.model,
+    controls: compatibleAgentControls(agent.agent.controls, selectedModel.model)
+  });
   const runId = globalThis.crypto.randomUUID();
   const runStartedAt = Date.now();
   await recordRunReceived({
     agentId,
-    body,
+    body: runBody,
     runId,
     selectedModel,
     session,
     store: props.stores.sessions
   });
   await recordSelectedModelWarnings({
+    body: runBody,
     runId,
     selectedModel,
     session,
     store: props.stores.sessions
   });
-  const memoryMetadata = runMemoryMetadata(agentId, body, selectedModel, runId);
-  const promptMessage = body.messages.at(-1);
+  const memoryMetadata = runMemoryMetadata(agentId, runBody, selectedModel, runId);
+  const promptMessage = runBody.messages.at(-1);
   const sessionStore = props.stores.sessions;
   const shouldPersistSessionMessages = session !== void 0 && sessionStore !== void 0 && !usesStoreAsAgentMemory(runAgent, sessionStore);
   if (shouldPersistSessionMessages) {
@@ -3230,7 +3306,7 @@ async function prepareAgentRun(c, props, abortSignal) {
   }
   const execution = createRunExecution({
     agentId,
-    body,
+    body: runBody,
     memoryMetadata,
     promptMessage,
     runAgent,
@@ -3239,12 +3315,12 @@ async function prepareAgentRun(c, props, abortSignal) {
   return {
     agentId,
     agent,
-    body,
+    body: runBody,
     memoryMetadata,
     execution,
     failureMessages: void 0,
     memoryCompactionLogged: false,
-    options: createRunOptions(body, agentId, session, abortSignal),
+    options: createRunOptions(runBody, agentId, session, abortSignal),
     runAgent,
     runId,
     runStartedAt,
@@ -3255,6 +3331,15 @@ async function prepareAgentRun(c, props, abortSignal) {
     shouldPersistSessionMessages
   };
 }
+function compatibleAgentControls(controls, model) {
+  const modelControls = model.controls;
+  const compatible = Object.fromEntries(
+    Object.entries(controls ?? {}).filter(
+      (entry) => typeof entry[1] === "string" && modelControls !== void 0 && Object.hasOwn(modelControls, entry[0]) && modelControls[entry[0]]?.options.includes(entry[1]) === true
+    )
+  );
+  return Object.keys(compatible).length === 0 ? void 0 : compatible;
+}
 async function resolveRunSession(c, body, agentId, stores) {
   if (body.sessionId !== void 0 && stores.sessions === void 0) {
     return unsupportedCapability(c, "sessions");
@@ -3298,12 +3383,15 @@ async function recordRunReceived(props) {
   if (props.body.toolConcurrency !== void 0) {
     input.toolConcurrency = props.body.toolConcurrency;
   }
-  if (props.body.metadata !== void 0 || props.selectedModel.ref !== void 0) {
+  if (props.body.metadata !== void 0 || props.selectedModel.ref !== void 0 || props.body.controls !== void 0) {
     const metadata = {};
     Object.assign(metadata, props.body.metadata);
     if (props.selectedModel.ref !== void 0) {
       metadata[STUDIO_MODEL_METADATA_KEY] = props.selectedModel.ref;
     }
+    if (props.body.controls !== void 0) {
+      metadata[STUDIO_CONTROLS_METADATA_KEY] = props.body.controls;
+    }
     input.metadata = metadata;
   }
   await appendSessionLog(props.store, runReceivedLog(input));
@@ -3323,10 +3411,13 @@ async function recordSelectedModelWarnings(props) {
       metadata: warning
     });
   }
-  if (sessionModelRef(props.session.metadata) !== props.selectedModel.ref) {
+  if (sessionModelRef(props.session.metadata) !== props.selectedModel.ref || props.body.controls !== void 0) {
     const metadata = {};
     Object.assign(metadata, props.session.metadata);
     metadata[STUDIO_MODEL_METADATA_KEY] = props.selectedModel.ref;
+    if (props.body.controls !== void 0) {
+      metadata[STUDIO_CONTROLS_METADATA_KEY] = props.body.controls;
+    }
     await props.store?.updateSessionMetadata?.(props.session.id, metadata);
   }
 }
@@ -3334,6 +3425,7 @@ function runMemoryMetadata(agentId, body, selectedModel, runId) {
   const metadata = { agentId };
   Object.assign(metadata, body.metadata);
   if (selectedModel.ref !== void 0) metadata[STUDIO_MODEL_METADATA_KEY] = selectedModel.ref;
+  if (body.controls !== void 0) metadata[STUDIO_CONTROLS_METADATA_KEY] = body.controls;
   metadata.studioRunId = runId;
   return metadata;
 }
@@ -3365,6 +3457,7 @@ function createRunOptions(body, agentId, session, abortSignal) {
   if (body.type === "messages" && body.toolConcurrency !== void 0) {
     options.toolConcurrency = body.toolConcurrency;
   }
+  if (body.type === "messages" && body.controls !== void 0) options.controls = body.controls;
   if (body.trace !== void 0) {
     options.trace = traceForRun(body.trace, agentId, session);
   } else if (session !== void 0) {