@cadenya/cadenya 1.0.0 → 1.0.2

package/src/types.ts

@@ -637,10 +637,8 @@ export interface AgentVariationSpec_Constraints {
    *  When not set, objectives are still swept at the system-wide 24 hour
    *  maximum — every objective eventually reaches a terminal state.
    * 
-   *  Note: no gnostic integer hint here on purpose. The Envoy gRPC-JSON
-   *  transcoder only accepts the canonical protobuf JSON form for
-   *  Durations — a "<seconds>s" string — so the SDKs must type this as a
-   *  string (like AgentScheduleSpec.every), not an integer.
+   *  SDKs represent this as a duration string, like AgentScheduleSpec.every,
+   *  rather than an integer.
    */
   inactivityTimeout?: string;
 }
@@ -658,7 +656,7 @@ export type AgentVariationSpecModelConfigReasoningEffort = 'REASONING_EFFORT_UNS
  */
 export interface AgentVariationSpec_ModelConfig {
   /**
-   * The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")
+   * The model identifier for the agent variation to use. Should be either the reference key (ai-provider.model-name) or the canonical model ID (e.g.: "model_ABC123")
    */
   modelId: string;
   /**
@@ -1278,9 +1276,12 @@ export interface CreateObjectiveRequest {
   subject?: SubjectAssertion;
   /**
    * Parameters forced onto this objective's tool calls. A pinned parameter
-   *  is an overlay on a tool's JSON schema: the parameter is removed from
-   *  what the LLM sees, and its value is always overwritten server-side with
-   *  the pinned value — the model cannot choose a different value for it.
+   *  is removed from the tool schema the LLM sees, and its value is always
+   *  overwritten server-side with the pinned value — the model cannot choose
+   *  a different value for it. By default a pinned key applies to every tool
+   *  with a top-level parameter of the same name; a tool set's overlays
+   *  (ToolSetSpec.overlays) can bind pinned keys to nested paths, differently
+   *  named parameters, or a subset of tools.
    */
   pinnedParameters?: Record<string, string>;
 }
@@ -1532,7 +1533,7 @@ export interface EnableModelRequest {
 
 export interface GetObjectiveDiagnosticsResponse {
   /**
-   * Diagnostics from the objective's most recent iteration.
+   * Context usage from the objective's most recent iteration.
    */
   diagnostics: ObjectiveDiagnostics;
 }
@@ -2086,7 +2087,7 @@ export type ModelSpec_Capability =
 export type NoticeLevel = 'LEVEL_UNSPECIFIED' | 'LEVEL_INFO' | 'LEVEL_WARN';
 
 /**
- * Notice is a non-terminal diagnostic emitted by the runtime when something
+ * Notice is a non-terminal event emitted by the runtime when something
  *  noteworthy but non-fatal happens during an objective — for example a
  *  just-in-time tool set failing to load, or a previously loaded tool being
  *  dropped because it was archived. Notices carry no structured payload; they
@@ -2259,10 +2260,10 @@ export interface ObjectiveContextWindowInfo {
 }
 
 /**
- * ObjectiveDiagnostics is the context-usage breakdown measured for a single
- *  iteration at request-assembly time. It reports how much of the context
- *  window each component occupies so tool parameters, memory cascades, and
- *  prompts can be tuned against real token usage.
+ * Context-usage breakdown measured for a single iteration at request-assembly
+ *  time. It reports how much of the context window each component occupies so
+ *  tool parameters, memory cascades, and prompts can be tuned against real
+ *  token usage.
  */
 export interface ObjectiveDiagnostics {
   /**
@@ -2580,6 +2581,12 @@ export interface ObjectiveToolCallInfo {
  *  short-lived signed URLs rather than inline bytes.
  */
 export interface ObjectiveToolCallResult {
+  /**
+   * The result content as recorded — which is what the model was shown.
+   *  When a tool set overlay transformed the result (ToolOverlay
+   *  result_actions), this is the transformed content; the adapter's raw
+   *  response is kept in the tool call's debug log, not here.
+   */
   content: Array<ObjectiveToolCallResult_ContentBlock>;
 }
 
@@ -2770,6 +2777,82 @@ export interface Page {
   nextCursor: string;
 }
 
+/**
+ * Default: ON_MISSING_FAIL.
+ */
+export type ParameterActionPinOnMissing = 'ON_MISSING_UNSPECIFIED' | 'ON_MISSING_FAIL' | 'ON_MISSING_SKIP';
+
+/**
+ * Bind the parameter to one of the objective's pinned parameters. It is
+ *  deleted from the schema (including any `required` entry), and on every
+ *  call the pinned value is written into the arguments, overwriting
+ *  anything the model supplied.
+ *  This is the authoritative-value action: the model never sees the
+ *  parameter and cannot influence it.
+ * 
+ *  `pin` differs from `set` with `{{ pinned_parameters.key }}` only in
+ *  how a missing key is handled (see `on_missing`) and in intent —
+ *  reading the tool set config, `pin` says "this comes from the caller".
+ */
+export interface ParameterAction_Pin {
+  path: string;
+  /**
+   * Key into the objective's pinned_parameters map. Need not equal the
+   *  last segment of `path` — this is how a pinned `orgId` reaches a
+   *  tool whose parameter is named `organizationId`.
+   */
+  pinnedParameter: string;
+  /**
+   * Default: ON_MISSING_FAIL.
+   */
+  onMissing: ParameterActionPinOnMissing;
+}
+
+/**
+ * Remove the parameter entirely. It is deleted from the schema
+ *  (including any `required` entry) and stripped from the arguments if
+ *  the model supplies it anyway. The tool receives no value for it — the
+ *  upstream default, if any, applies. Use this to save context on
+ *  parameters the model has no business setting (pagination cursors,
+ *  expansion flags, debug toggles).
+ */
+export interface ParameterAction_Remove {
+  path: string;
+}
+
+/**
+ * Force the parameter to a value. It is deleted from the schema
+ *  (including any `required` entry), and on every call the rendered
+ *  value is written into the arguments, overwriting anything the model
+ *  supplied.
+ * 
+ *  `value_template` is a Liquid template rendered against the objective:
+ * 
+ *    {{ pinned_parameters.<key> }}  the objective's pinned parameters
+ *    {{ objective.id }}             the objective's id
+ *    {{ objective.external_id }}    the objective's external id
+ *    {{ objective.labels.<key> }}   the objective's labels
+ * 
+ *  Templates render with strict variables: referencing a pinned
+ *  parameter or label that does not exist fails the call rather than
+ *  rendering an empty value.
+ * 
+ *  Tool set secrets are intentionally not exposed here: overlay-set
+ *  values are recorded as tool call arguments in events and tool call
+ *  history, and would leak. Use adapter headers for credentials.
+ * 
+ *  The rendered string is coerced to the parameter's declared schema
+ *  type: for a non-string parameter (integer, number, boolean, object,
+ *  array) the output is parsed as JSON. A value that fails to parse
+ *  errors the tool call. Prefer `pin` when the value is simply a pinned
+ *  parameter — it fails loudly when the key is absent instead of
+ *  rendering an empty string.
+ */
+export interface ParameterAction_Set {
+  path: string;
+  valueTemplate: string;
+}
+
 /**
  * Pause agent schedule request.
  */
@@ -2934,6 +3017,67 @@ export interface RestoreToolRequest {
   id?: string;
 }
 
+/**
+ * Default: ON_ERROR_RAW_CONTENT.
+ */
+export type ResultActionTransformOnError = 'ON_ERROR_UNSPECIFIED' | 'ON_ERROR_RAW_CONTENT' | 'ON_ERROR_FAIL';
+
+/**
+ * Replace the result's text content with a rendered Liquid template.
+ *  Used to compact verbose responses to the fields the model actually
+ *  needs, or to rewrite a JSON response into a smaller JSON document.
+ * 
+ *  `content_template` is rendered against the call:
+ * 
+ *    {{ result.text }}        the result's text content (text blocks
+ *                             joined with newlines)
+ *    {{ result.json }}        result.text parsed as JSON — objects and
+ *                             arrays are navigable (`result.json.items`,
+ *                             `| map: "id"`); absent when the text is not
+ *                             valid JSON
+ *    {{ result.blocks }}      every content block: [{type, text?,
+ *                             mime_type?, size_bytes?}]
+ *    {{ parameters }}         the arguments the tool was called with,
+ *                             after parameter actions were applied
+ *    {{ tool.name }}          the tool's metadata.name
+ *    {{ tool.llm_tool_name }} the name the model called it by
+ *    {{ pinned_parameters }}  the objective's pinned parameters
+ *    {{ objective.id }} / {{ objective.external_id }} /
+ *    {{ objective.labels.<key> }}
+ * 
+ *  Templates render with strict variables: referencing `result.json` on
+ *  a non-JSON result, or any other undefined variable, is a render error
+ *  and `on_error` decides the outcome. The `json` filter pretty-prints a
+ *  value as JSON; `sanitized_json` emits it compact and escaped for
+ *  embedding.
+ * 
+ *  Transforms are text-only. `result.text` and `result.json` are built
+ *  from the result's text blocks; media blocks (images, audio) are opaque
+ *  to the template and pass through unchanged. The rendered text replaces
+ *  the text blocks as a single text block. A result with no text blocks
+ *  at all (an image-only or audio-only result) is out of scope: the
+ *  transform is skipped, the result is recorded as returned, and the
+ *  skip is noted in the tool call's debug log — this is not an `on_error`
+ *  case, nothing was attempted. The one exception is `expect_json`, where
+ *  a result with no text is a violated precondition and `on_error`
+ *  applies.
+ */
+export interface ResultAction_Transform {
+  contentTemplate: string;
+  /**
+   * Default: ON_ERROR_RAW_CONTENT.
+   */
+  onError: ResultActionTransformOnError;
+  /**
+   * Require the tool result to have text content that parses as JSON
+   *  before rendering. A non-JSON (or text-less) result is then an error
+   *  subject to `on_error` even if the template never reads
+   *  `result.json`. Off by default: `result.json` is simply absent for
+   *  non-JSON results, and text-less results skip the transform.
+   */
+  expectJson: boolean;
+}
+
 /**
  * Resume agent schedule request.
  */
@@ -3039,6 +3183,26 @@ export interface SearchToolsOrToolSetsResponse {
   agents: Array<Agent>;
 }
 
+/**
+ * A single selector condition.
+ */
+export type Selector_Condition =
+  | Selector_Condition_Attribute
+  | Selector_Condition_HasParameter
+  | Selector_Condition_Tools;
+
+/**
+ * An explicit list of tools, matched on spec.llm_tool_name — the name
+ *  the model calls the tool by. It identifies a tool across versions:
+ *  just-in-time MCP sets keep one tool per signature and every version
+ *  shares the LLM name, so the condition keeps matching as the source
+ *  evolves. Any name in the list matches (OR). Names of tools not (or
+ *  not yet) present in the set are allowed and match nothing.
+ */
+export interface Selector_ToolNames {
+  names?: Array<string>;
+}
+
 /**
  * SetToolCallContentRequest lets an external API consumer supply the result
  *  of a bare tool call (one whose tool set has no execution adapter). Used
@@ -3405,6 +3569,12 @@ export interface ToolCalled {
    * The arguments passed to the tool.
    */
   arguments?: Record<string, unknown>;
+  /**
+   * Whether the runtime authorized this call's arguments to be exposed in
+   *  public widget events. This records the resolved policy at call time so
+   *  consumers do not need to re-evaluate the tool set's current overlays.
+   */
+  argumentsExposedInWidgets?: boolean;
 }
 
 export interface ToolDenied {
@@ -3433,9 +3603,205 @@ export interface ToolInfo {
    * Content signature identifying the tool within its tool set: a hash of the
    *  sanitized llm_tool_name, description, and canonical parameters. Two tools
    *  with the same llm_tool_name but different parameters or description (as
-   *  MCP servers may return per user) have distinct signatures.
+   *  MCP servers may return per user) have distinct signatures. Computed over
+   *  the raw spec — overlays do not change a tool's signature.
    */
   signature: string;
+  /**
+   * Keys of the tool set's overlays whose selectors match this tool
+   *  (ToolSetSpec.overlays), in evaluation order. Disabled overlays are
+   *  excluded. An overlay is listed when its selector matches even if none
+   *  of its actions changed this tool's schema (all its paths were absent),
+   *  so this answers "which policies apply to this tool" — diff
+   *  effective_parameters against spec.parameters for "what changed".
+   *  Empty when no overlay applies.
+   */
+  overlays?: Array<string>;
+  /**
+   * The parameter schema as presented to the model: spec.parameters after
+   *  every matching overlay's parameter actions have been applied, in order,
+   *  including maintenance of the schema's `required` list. Actions whose
+   *  outcome depends on the objective (pin with ON_MISSING_SKIP) are applied
+   *  as if the pinned key were present, so this reflects the intended steady
+   *  state rather than any one objective. Equals spec.parameters when no
+   *  overlay applies. Result actions have no effect here.
+   */
+  effectiveParameters?: Record<string, unknown>;
+}
+
+/**
+ * A tool overlay is a policy attached to a tool set that reshapes the tools
+ *  the model sees and calls. It pairs a selector (which tools it applies to)
+ *  with actions that run before a call — rewriting the tool's parameter
+ *  schema and the arguments the model supplied — and after a call —
+ *  rewriting the result before it enters the model's context. It can also
+ *  explicitly allow the final call arguments to cross the otherwise-private
+ *  widget API boundary.
+ * 
+ *  Overlays exist for three reasons:
+ * 
+ *    - Authority. Adapter-derived tool sets (OpenAPI especially) expose many
+ *      parameters the model must never guess — a workspace id, a tenant id,
+ *      an account scope. Overlays bind those parameters to the objective's
+ *      `pinned_parameters` (see CreateObjectiveRequest.pinned_parameters):
+ *      the parameter disappears from the schema and the value is forced
+ *      server-side, so the model has no opportunity to supply a different
+ *      one.
+ *    - Context. Large specs carry pagination cursors, expansion flags and
+ *      verbose responses that cost tokens without helping the model.
+ *      Overlays strip parameters, fix them to literals, and compact results.
+ *    - Widget presentation. Tool arguments are private by default. An overlay
+ *      can opt matching tools into exposing their final call arguments in
+ *      visitor-facing widget events so an embedding UI can select a custom
+ *      renderer or presentation.
+ * 
+ *  Pinned parameters and overlays are complementary: pinned parameters are
+ *  *data* supplied per objective (or per widget session) by the caller;
+ *  overlays are *policy* authored once on the tool set. Pinning by name
+ *  still works without an overlay — a pinned key that matches a top-level
+ *  parameter name is applied to every tool in the objective — overlays are
+ *  for the cases that needs more: nested paths, renamed keys, a subset of
+ *  tools, or values that are literals rather than caller-supplied.
+ * 
+ *  Evaluation model:
+ * 
+ *    - Overlays are evaluated in list order; within an overlay, actions are
+ *      evaluated in list order. Later actions win on the same path (a `set`
+ *      followed by a `remove` leaves the parameter removed).
+ *    - The parameter schema the model sees is computed when tools are
+ *      assembled for an objective, so pre-call actions can consult that
+ *      objective's pinned parameters (this is what makes `pin` with
+ *      ON_MISSING_SKIP meaningful). Argument rewriting runs on every call.
+ *    - An action whose `path` does not exist in the tool's parameter schema
+ *      changes nothing in the schema the model sees. This is deliberate: a
+ *      broad selector (every `list_*` tool) may match tools with different
+ *      shapes, and one overlay should be able to cover all of them without
+ *      erroring on the ones that lack a given parameter. At call time the
+ *      model's arguments can still not widen what it controls: `remove`
+ *      strips the path whether or not it is declared, and `set`/`pin`
+ *      overwrite a value the model sent at an undeclared path (a schema this
+ *      evaluator cannot see through, e.g. behind $ref/allOf) while injecting
+ *      nothing into tools that lack the parameter.
+ *    - Overlays apply to just-in-time tool sets as well; the tools are
+ *      evaluated against overlays at the moment they are loaded.
+ *    - Result actions run once, when the tool call's result is recorded; the
+ *      stored result is the transformed one, so every reader (the model,
+ *      compaction, the API) sees the same content. They are not supported on
+ *      bare tool sets.
+ */
+export interface ToolOverlay {
+  /**
+   * Identifies the overlay within its tool set. Unique across the tool
+   *  set's overlays (enforced by the server), stable across reorders, and
+   *  surfaced in tool call messages ("parameter removed by overlay
+   *  strip-list-knobs") so an operator can trace a rewritten call back to
+   *  the policy that rewrote it. Referenced by ToolInfo.overlays and the
+   *  ListToolsRequest.overlays filter.
+   */
+  key: string;
+  /**
+   * Which tools this overlay applies to. Required; an empty selector
+   *  (no conditions) matches every tool in the set.
+   */
+  selector: ToolOverlay_Selector;
+  /**
+   * Pre-call actions, applied in order. See ParameterAction.
+   */
+  parameterActions?: Array<ToolOverlay_ParameterAction>;
+  /**
+   * Post-call actions, applied in order. See ResultAction.
+   */
+  resultActions?: Array<ToolOverlay_ResultAction>;
+  /**
+   * When true the overlay is retained in the spec but not evaluated. Lets an
+   *  operator switch a policy off to diagnose a misbehaving tool without
+   *  deleting it and losing the configuration.
+   */
+  disabled: boolean;
+  /**
+   * Arguments may carry sensitive customer data, including values injected by
+   *  parameter actions, so they stay private unless an overlay enables them.
+   * 
+   *  Unset means this overlay has no opinion. When several enabled overlays
+   *  match a tool, they are evaluated in list order and the last overlay that
+   *  supplies this policy wins. If none supplies it, arguments stay private.
+   *  Disabled overlays never participate.
+   */
+  widgetArgumentExposure?: ToolOverlay_WidgetArgumentExposure;
+}
+
+/**
+ * A pre-call action. Parameter actions rewrite the tool's parameter
+ *  schema as presented to the model and the arguments the model supplies
+ *  when it calls the tool. Both sides are always kept in agreement: a
+ *  parameter that is hidden from the schema is also stripped from (or
+ *  forced in) the arguments, so the model can neither see nor smuggle it.
+ */
+export type ToolOverlay_ParameterAction =
+  | ToolOverlay_ParameterAction_Remove
+  | ToolOverlay_ParameterAction_Set
+  | ToolOverlay_ParameterAction_Pin;
+
+/**
+ * A dotted path into a tool's parameter schema. Each segment is a property
+ *  name; the path `filter.workspaceId` addresses
+ *  `properties.filter.properties.workspaceId` in the schema and
+ *  `arguments.filter.workspaceId` in the call. Only object properties are
+ *  addressable — there is no array indexing, wildcarding or filtering.
+ * 
+ *  This is deliberately not JSONPath: every action needs a single,
+ *  unambiguous location in both the schema and the arguments so that
+ *  removing a parameter from the schema and stripping it from the call are
+ *  guaranteed to agree.
+ */
+export interface ToolOverlay_ParameterPath {
+  path: string;
+}
+
+/**
+ * A post-call action. Result actions rewrite a tool call's result after
+ *  the adapter returns and before it is recorded: the transformed content
+ *  is what is stored and what the model reads (ObjectiveToolCallResult
+ *  content). The adapter's raw response is kept in the tool call's debug
+ *  log for operators; it is not otherwise retained.
+ * 
+ *  Result actions apply to MCP, OpenAPI and HTTP tool sets. They are not
+ *  supported on bare tool sets — a bare tool's content is supplied by an
+ *  external consumer, so there is nothing for the platform to reshape —
+ *  and a tool set whose adapter is `bare` rejects overlays that carry
+ *  result actions.
+ * 
+ *  When several matching overlays carry transforms they run in overlay
+ *  order, each one reading the previous one's output.
+ */
+export type ToolOverlay_ResultAction =
+  | ToolOverlay_ResultAction_Transform;
+
+/**
+ * Default: OPERATOR_AND.
+ */
+export type ToolOverlaySelectorOperator = 'OPERATOR_UNSPECIFIED' | 'OPERATOR_AND' | 'OPERATOR_OR';
+
+/**
+ * Which tools in the tool set an overlay applies to. Conditions are
+ *  combined with `operator`; an overlay with no conditions matches every
+ *  tool in the set.
+ */
+export interface ToolOverlay_Selector {
+  conditions?: Array<Selector_Condition>;
+  /**
+   * Default: OPERATOR_AND.
+   */
+  operator: ToolOverlaySelectorOperator;
+}
+
+/**
+ * Controls whether matching tool calls may expose their final arguments to
+ *  visitor-facing widget events. The containing message's presence means the
+ *  overlay has an opinion; enabled selects whether that opinion is on or off.
+ */
+export interface ToolOverlay_WidgetArgumentExposure {
+  enabled: boolean;
 }
 
 export interface ToolResult {
@@ -3481,7 +3847,7 @@ export type ToolSetAdapter_ApprovalRequirementFilter =
   | ToolSetAdapter_ApprovalRequirementFilter_Always
   | ToolSetAdapter_ApprovalRequirementFilter_Only;
 
-export type ToolSetAdapterAttributeFilterAttribute = 'ATTRIBUTE_UNSPECIFIED' | 'ATTRIBUTE_NAME' | 'ATTRIBUTE_TITLE' | 'ATTRIBUTE_DESCRIPTION';
+export type ToolSetAdapterAttributeFilterAttribute = 'ATTRIBUTE_UNSPECIFIED' | 'ATTRIBUTE_NAME' | 'ATTRIBUTE_TITLE' | 'ATTRIBUTE_DESCRIPTION' | 'ATTRIBUTE_LLM_TOOL_NAME';
 
 /**
  * Single attribute filter
@@ -3508,6 +3874,27 @@ export interface ToolSetAdapter_Bare {
 }
 
 export interface ToolSetAdapter_HTTP {
+  /**
+   * Base URL for dispatching tool calls.
+   * 
+   *  May be templated. Two reference forms are supported, and they resolve
+   *  in a single pass each so neither can inject into the other:
+   * 
+   *    ${SECRET_NAME}                 a workspace or tool set secret
+   *    {{ pinned_parameters.<key> }}  the objective's pinned parameters
+   *      (see CreateObjectiveRequest.pinned_parameters)
+   * 
+   *  Pinned parameters are what make a per-tenant host possible: one tool
+   *  set can serve every customer of a product that assigns each of them
+   *  their own subdomain, e.g.
+   * 
+   *    https://{{ pinned_parameters.tenant }}.example.com
+   * 
+   *  Because the value may be a template rather than a literal URL, this
+   *  field is not constrained to a URI shape. It is validated as an
+   *  absolute http(s) URL after references are resolved, both on write
+   *  (with references stubbed) and again before each tool call.
+   */
   baseUrl?: string;
   headers?: Record<string, string>;
 }
@@ -3632,6 +4019,15 @@ export interface ToolSetSecretSpec {
 export interface ToolSetSpec {
   description?: string;
   adapter: ToolSetAdapter;
+  /**
+   * Overlays applied to this tool set's tools, evaluated in order. See
+   *  ToolOverlay. Overlay keys must be unique within the list.
+   * 
+   *  As a repeated field this is replaced wholesale on update: an
+   *  update_mask of `spec.overlays` swaps the entire list for the one in the
+   *  request. Read-modify-write to add or remove a single overlay.
+   */
+  overlays?: Array<ToolOverlay>;
 }
 
 /**
@@ -3668,8 +4064,9 @@ export interface ToolSpec {
    */
   parameters: Record<string, unknown>;
   /**
-   * Configuration for this specific tool. Transport/Protocol are derived from the tool set adapter, while specifics
-   *  such as endpoint, method, etc, are stored on the tool itself.
+   * Configuration for this specific tool. Its transport is derived from the
+   *  tool set adapter, while details such as endpoint and method are stored on
+   *  the tool itself.
    * 
    *  Required, and exactly one adapter must be set.
    */
@@ -4374,13 +4771,13 @@ export interface WidgetSessionSpec {
   tokenExpiresAt?: string;
   /**
    * Parameters forced onto tool calls made by this session's conversations.
-   *  A pinned parameter is an overlay on a tool's JSON schema: the parameter
-   *  is removed from what the LLM sees, and its value is always overwritten
-   *  server-side with the pinned value — so the model cannot be tricked into
-   *  calling a tool with a different id than the one the session was minted
-   *  for (e.g. pin "workspaceId" for an OpenAPI tool with a
-   *  /workspaces/{workspaceId} path). Flows to every objective the session
-   *  creates.
+   *  A pinned parameter is removed from the tool schema the LLM sees, and its
+   *  value is always overwritten server-side with the pinned value — so the
+   *  model cannot be tricked into calling a tool with a different id than the
+   *  one the session was minted for (e.g. pin "workspaceId" for an OpenAPI
+   *  tool with a /workspaces/{workspaceId} path). Flows to every objective
+   *  the session creates. See ToolSetSpec.overlays for binding pinned keys to
+   *  nested or differently named parameters.
    */
   pinnedParameters?: Record<string, string>;
 }
@@ -4647,6 +5044,17 @@ export interface ToolSetAdapter_OpenAPI_Url {
   /**
    * Base URL for dispatching tool calls. If set, overrides the server
    *  resolved from the spec's servers array.
+   * 
+   *  May be templated with the same two reference forms the HTTP adapter's
+   *  base_url accepts:
+   * 
+   *    ${SECRET_NAME}                 a workspace or tool set secret
+   *    {{ pinned_parameters.<key> }}  the objective's pinned parameters
+   * 
+   *  A spec written against a single host can therefore be dispatched to a
+   *  per-tenant one, e.g. https://{{ pinned_parameters.tenant }}.example.com,
+   *  without cloning the tool set per customer. Validated as an absolute
+   *  http(s) URL after references are resolved rather than as a literal URI.
    */
   baseUrl?: string;
   /**
@@ -4674,6 +5082,17 @@ export interface ToolSetAdapter_OpenAPI_UploadId {
   /**
    * Base URL for dispatching tool calls. If set, overrides the server
    *  resolved from the spec's servers array.
+   * 
+   *  May be templated with the same two reference forms the HTTP adapter's
+   *  base_url accepts:
+   * 
+   *    ${SECRET_NAME}                 a workspace or tool set secret
+   *    {{ pinned_parameters.<key> }}  the objective's pinned parameters
+   * 
+   *  A spec written against a single host can therefore be dispatched to a
+   *  per-tenant one, e.g. https://{{ pinned_parameters.tenant }}.example.com,
+   *  without cloning the tool set per customer. Validated as an absolute
+   *  http(s) URL after references are resolved rather than as a literal URI.
    */
   baseUrl?: string;
   /**
@@ -4685,6 +5104,55 @@ export interface ToolSetAdapter_OpenAPI_UploadId {
   serverName?: string;
 }
 
+export interface Selector_Condition_Attribute {
+  type: 'attribute';
+  /**
+   * Match on a tool attribute (name, title, description,
+   *  llm_tool_name) with a string matcher — the same filter used by
+   *  the adapter's include/exclude lists.
+   */
+  attribute: ToolSetAdapter_AttributeFilter;
+}
+
+export interface Selector_Condition_HasParameter {
+  type: 'hasParameter';
+  /**
+   * Match tools whose parameter schema contains the given path. This
+   *  is the usual way to target "every tool that takes a workspaceId"
+   *  without enumerating tools by name.
+   */
+  hasParameter: ToolOverlay_ParameterPath;
+}
+
+export interface Selector_Condition_Tools {
+  type: 'tools';
+  /**
+   * Match specific tools by LLM tool name. The direct way to assign an
+   *  overlay to one tool (or a handful) without writing a matcher.
+   */
+  tools: Selector_ToolNames;
+}
+
+export interface ToolOverlay_ParameterAction_Remove {
+  type: 'remove';
+  remove: ParameterAction_Remove;
+}
+
+export interface ToolOverlay_ParameterAction_Set {
+  type: 'set';
+  set: ParameterAction_Set;
+}
+
+export interface ToolOverlay_ParameterAction_Pin {
+  type: 'pin';
+  pin: ParameterAction_Pin;
+}
+
+export interface ToolOverlay_ResultAction_Transform {
+  type: 'transform';
+  transform: ResultAction_Transform;
+}
+
 export interface ToolSpec_Config_Http {
   type: 'http';
   http: Config_HTTP;
@@ -5073,13 +5541,13 @@ export interface WidgetSessionSpecParam {
   expiresAt?: string;
   /**
    * Parameters forced onto tool calls made by this session's conversations.
-   *  A pinned parameter is an overlay on a tool's JSON schema: the parameter
-   *  is removed from what the LLM sees, and its value is always overwritten
-   *  server-side with the pinned value — so the model cannot be tricked into
-   *  calling a tool with a different id than the one the session was minted
-   *  for (e.g. pin "workspaceId" for an OpenAPI tool with a
-   *  /workspaces/{workspaceId} path). Flows to every objective the session
-   *  creates.
+   *  A pinned parameter is removed from the tool schema the LLM sees, and its
+   *  value is always overwritten server-side with the pinned value — so the
+   *  model cannot be tricked into calling a tool with a different id than the
+   *  one the session was minted for (e.g. pin "workspaceId" for an OpenAPI
+   *  tool with a /workspaces/{workspaceId} path). Flows to every objective
+   *  the session creates. See ToolSetSpec.overlays for binding pinned keys to
+   *  nested or differently named parameters.
    */
   pinnedParameters?: Record<string, string>;
 }