@wildix/wilma-agents-client 1.0.27 → 1.0.28

package/dist-types/models/models_0.d.ts

@@ -1,5 +1,5 @@
 import type { DocumentType as __DocumentType } from "@smithy/types";
-import type { ActorType, AgentHandoverPipelineType, AgentHandoverVariant, AgentHangupPipelineType, AgentStatus, AgentToolPipelineType, AgentTransferPipelineType, AgentTransferVariant, AgentVariableType, AgentVisibility, AgentWorkflowEntryBehavior, AgentWorkflowFailureKind, AgentWorkflowLayout, AgentWorkflowMessageButtonVariant, ChannelType, SandboxNetworkAccess, SandboxSize, WebSearchContextSize } from "./enums";
+import type { ActorType, AgentGuardrailErrorMode, AgentGuardrailMode, AgentGuardrailPreset, AgentGuardrailSensitivity, AgentGuardrailWindow, AgentHandoverPipelineType, AgentHandoverVariant, AgentHangupPipelineType, AgentStatus, AgentToolPipelineType, AgentTransferPipelineType, AgentTransferVariant, AgentVariableType, AgentVisibility, AgentWorkflowEntryBehavior, AgentWorkflowFailureKind, AgentWorkflowLayout, AgentWorkflowMessageButtonVariant, ChannelType, SandboxNetworkAccess, SandboxSize, WebSearchContextSize } from "./enums";
 /**
  * A user or group that access is granted to.
  * @public
@@ -1332,6 +1332,295 @@ export declare namespace AgentCapability {
         _: (name: string, value: any) => T;
     }
 }
+/**
+ * Refuse the turn. The agent's model is never called, no tool runs, and the caller is answered with `message` instead. The session stays alive and the conversation continues, so on a check meant to redirect rather than stop — 'let me take a few details first' — the message is doing the work.
+ * @public
+ */
+export interface AgentGuardrailBlockAction {
+    /**
+     * Said to the caller in place of the agent's reply. Falls back to a channel default when unset.
+     * @public
+     */
+    message?: string | undefined;
+}
+/**
+ * End the session. It lands in SessionStatus TERMINATED — not STOPPED, which is what a user asking to stop means — so a refused session is never read back as a clean finish. On voice this hangs up the call; on the other channels the session simply accepts no further turns.
+ * @public
+ */
+export interface AgentGuardrailEndAction {
+    /**
+     * Said to the caller before the session ends.
+     * @public
+     */
+    message?: string | undefined;
+}
+/**
+ * Record the verdict and let the turn through. The rollout mode: every guardrail should run here first, against real traffic, until its trips are read and its sensitivity is tuned. A tripped check still emits GuardrailTrippedEvent and still appears in the trace, which is what makes this a tuning tool rather than a switched-off check.
+ * @public
+ */
+export interface AgentGuardrailObserveAction {
+}
+/**
+ * Mask the matched spans and let the turn continue. The mask is chosen by the platform and is not configurable — a tenant-authored placeholder that collides with real text, or that the model reads as an instruction, is worse than having no choice. Only valid on checks that return spans (PII, SECRETS).
+ * @public
+ */
+export interface AgentGuardrailRedactAction {
+}
+/**
+ * What happens when a check trips. Exactly one member is set.
+ *
+ *     Ordered by severity: observe < redact < block < end. When more than one check trips in the same call the
+ *     most severe action wins and ties break on the order of `checks`, so a set can mix an observed check with
+ *     an enforced one without the observation weakening the enforcement.
+ *
+ *     There is no hand-over member yet. Handing a session to a human is a different mechanism on every channel
+ *     — a voice transfer, a chat assignment, an assistant with no human behind it — and wiring a guardrail into
+ *     all of them is out of proportion to the rest of this feature. Until AgentHandoverCapability has a runtime
+ *     on more than one channel, the crisis path is a block whose message routes the caller.
+ * @public
+ */
+export type AgentGuardrailAction = AgentGuardrailAction.BlockMember | AgentGuardrailAction.EndMember | AgentGuardrailAction.ObserveMember | AgentGuardrailAction.RedactMember | AgentGuardrailAction.$UnknownMember;
+/**
+ * @public
+ */
+export declare namespace AgentGuardrailAction {
+    /**
+     * Record the verdict and let the turn through. The rollout mode: every guardrail should run here first, against real traffic, until its trips are read and its sensitivity is tuned. A tripped check still emits GuardrailTrippedEvent and still appears in the trace, which is what makes this a tuning tool rather than a switched-off check.
+     * @public
+     */
+    interface ObserveMember {
+        observe: AgentGuardrailObserveAction;
+        redact?: never;
+        block?: never;
+        end?: never;
+        $unknown?: never;
+    }
+    /**
+     * Mask the matched spans and let the turn continue. The mask is chosen by the platform and is not configurable — a tenant-authored placeholder that collides with real text, or that the model reads as an instruction, is worse than having no choice. Only valid on checks that return spans (PII, SECRETS).
+     * @public
+     */
+    interface RedactMember {
+        observe?: never;
+        redact: AgentGuardrailRedactAction;
+        block?: never;
+        end?: never;
+        $unknown?: never;
+    }
+    /**
+     * Refuse the turn. The agent's model is never called, no tool runs, and the caller is answered with `message` instead. The session stays alive and the conversation continues, so on a check meant to redirect rather than stop — 'let me take a few details first' — the message is doing the work.
+     * @public
+     */
+    interface BlockMember {
+        observe?: never;
+        redact?: never;
+        block: AgentGuardrailBlockAction;
+        end?: never;
+        $unknown?: never;
+    }
+    /**
+     * End the session. It lands in SessionStatus TERMINATED — not STOPPED, which is what a user asking to stop means — so a refused session is never read back as a clean finish. On voice this hangs up the call; on the other channels the session simply accepts no further turns.
+     * @public
+     */
+    interface EndMember {
+        observe?: never;
+        redact?: never;
+        block?: never;
+        end: AgentGuardrailEndAction;
+        $unknown?: never;
+    }
+    /**
+     * @public
+     */
+    interface $UnknownMember {
+        observe?: never;
+        redact?: never;
+        block?: never;
+        end?: never;
+        $unknown: [string, any];
+    }
+    /**
+     * @deprecated unused in schema-serde mode.
+     *
+     */
+    interface Visitor<T> {
+        observe: (value: AgentGuardrailObserveAction) => T;
+        redact: (value: AgentGuardrailRedactAction) => T;
+        block: (value: AgentGuardrailBlockAction) => T;
+        end: (value: AgentGuardrailEndAction) => T;
+        _: (name: string, value: any) => T;
+    }
+}
+/**
+ * A check written by the tenant. A name and a prompt is the whole surface: no category enum can express the rules customers actually buy, such as refusing to quote a price before qualifying.
+ * @public
+ */
+export interface AgentGuardrailCustomCheck {
+    /**
+     * Natural-language description of what a custom check looks for. Describe the *content* to be caught, not an instruction to the checker: 'The caller is asking about cryptocurrency investments' works, 'Block all content about crypto' does not, and a negative definition ('anything except billing questions') reliably misfires.
+     * @public
+     */
+    instructions: string;
+    /**
+     * Up to five turns that should trip this check. They steer the model's judgement and are NOT matched literally — a description plus examples catches the plural, the typo and the paraphrase that a term list misses.
+     * @public
+     */
+    examples?: string[] | undefined;
+}
+/**
+ * A check backed by one of the platform's prebuilt prompts.
+ * @public
+ */
+export interface AgentGuardrailPresetCheck {
+    /**
+     * A prebuilt check. Each preset is a platform-maintained prompt shipped in code and versioned with the
+     *     platform, not a tenant row — so a support question about what a preset caught has one answer. A preset
+     *     check is otherwise an ordinary AgentGuardrailCheck: its sensitivity and action are the tenant's to set,
+     *     and `notes` narrows its prompt without replacing it.
+     * @public
+     */
+    preset: AgentGuardrailPreset;
+    /**
+     * Appended to the preset's prompt. For narrowing, not redefining — 'ignore card numbers read back after our own IVR prompts for them' — so the preset keeps its maintenance while fitting a tenant whose product would otherwise fight it.
+     * @public
+     */
+    notes?: string | undefined;
+}
+/**
+ * What a check is: one of the platform's presets, or a prompt the tenant wrote. Exactly one member is set.
+ * @public
+ */
+export type AgentGuardrailCheckKind = AgentGuardrailCheckKind.CustomMember | AgentGuardrailCheckKind.PresetMember | AgentGuardrailCheckKind.$UnknownMember;
+/**
+ * @public
+ */
+export declare namespace AgentGuardrailCheckKind {
+    /**
+     * A check backed by one of the platform's prebuilt prompts.
+     * @public
+     */
+    interface PresetMember {
+        preset: AgentGuardrailPresetCheck;
+        custom?: never;
+        $unknown?: never;
+    }
+    /**
+     * A check written by the tenant. A name and a prompt is the whole surface: no category enum can express the rules customers actually buy, such as refusing to quote a price before qualifying.
+     * @public
+     */
+    interface CustomMember {
+        preset?: never;
+        custom: AgentGuardrailCustomCheck;
+        $unknown?: never;
+    }
+    /**
+     * @public
+     */
+    interface $UnknownMember {
+        preset?: never;
+        custom?: never;
+        $unknown: [string, any];
+    }
+    /**
+     * @deprecated unused in schema-serde mode.
+     *
+     */
+    interface Visitor<T> {
+        preset: (value: AgentGuardrailPresetCheck) => T;
+        custom: (value: AgentGuardrailCustomCheck) => T;
+        _: (name: string, value: any) => T;
+    }
+}
+/**
+ * One thing the checker is asked about a turn. There is deliberately no `enabled` flag: a check that
+ *     should not run is removed, so a published version never carries a switched-off check that reads like
+ *     policy.
+ * @public
+ */
+export interface AgentGuardrailCheck {
+    /**
+     * Name of a check, unique within a guardrail set. Stable and machine-facing: session events and trace spans report a verdict by this name, so a reader needs no copy of the agent definition to tell which check fired.
+     * @public
+     */
+    name: string;
+    description?: string | undefined;
+    /**
+     * What a check is: one of the platform's presets, or a prompt the tenant wrote. Exactly one member is set.
+     * @public
+     */
+    kind: AgentGuardrailCheckKind;
+    /**
+     * How much confidence a verdict needs before it counts as tripped. The checker reports a confidence per
+     *     check and this is the threshold against it, so raising sensitivity catches more and costs more false
+     *     positives without changing the prompt or the model: `low` trips only on high confidence, `medium` on
+     *     high and medium, `high` on anything but a clear pass. Defaults to MEDIUM.
+     * @public
+     */
+    sensitivity?: AgentGuardrailSensitivity | undefined;
+    /**
+     * Overrides AgentGuardrailInput.action for this check alone.
+     * @public
+     */
+    action?: AgentGuardrailAction | undefined;
+}
+/**
+ * Screening applied to what reaches the model.
+ *
+ *     There is deliberately no bundle or preset-group member. A named group that expands to a set of checks
+ *     reads like convenience and behaves like version skew: the same agent definition would mean different
+ *     things before and after a platform release, invisibly to the tenant who published it. Listing the checks
+ *     costs a few lines in a document the console writes anyway, and the published version then states exactly
+ *     what it enforces.
+ * @public
+ */
+export interface AgentGuardrailInput {
+    /**
+     * The checks to run, evaluated together in one call. Absent or empty means no screening.
+     * @public
+     */
+    checks?: AgentGuardrailCheck[] | undefined;
+    /**
+     * The model that runs the checks. Defaults to the platform's guardrail model — deliberately small and fast, and deliberately not the agent's own, whose cost and latency are what this exists to avoid spending on a bad turn.
+     * @public
+     */
+    model?: string | undefined;
+    /**
+     * Action for checks that declare none. Defaults to a block.
+     * @public
+     */
+    action?: AgentGuardrailAction | undefined;
+    /**
+     * Runs the checker before the agent's model (BLOCKING) or alongside it (PARALLEL). Blocking costs the checker's latency on every turn but guarantees that a refused turn spent no tokens and fired no tool; parallel adds no latency and is the right trade on voice, where the delay is audible, at the risk that part of a reply reaches the caller and that a tool has already run before the cancellation lands. Defaults to BLOCKING.
+     * @public
+     */
+    mode?: AgentGuardrailMode | undefined;
+    /**
+     * What happens when the checker itself errors or times out. OPEN lets the turn through unscreened and records GuardrailFailedEvent, so an unscreened turn is a fact in the log rather than an absence; CLOSED refuses it. Defaults to OPEN: an agent that stops answering because a small model had a bad minute is a worse and far likelier outage than the rare turn that goes unscreened. Background tasks, where nobody is waiting and a retry is free, are the case for CLOSED.
+     * @public
+     */
+    errorMode?: AgentGuardrailErrorMode | undefined;
+    /**
+     * How much of the conversation the checker sees. Defaults to LAST_WITH_PRIOR, because the jailbreaks worth catching are built across several turns — establish a fiction, then cash it in — and a checker shown only the last turn sees an innocuous sentence. There is no full-transcript option: screening a whole call on every turn would make the guardrail dearer than the agent.
+     * @public
+     */
+    window?: AgentGuardrailWindow | undefined;
+}
+/**
+ * Turn screening, by side. Only `input` exists: it guards what reaches the model, and output screening is a separate policy with different actions, added here when it is built.
+ * @public
+ */
+export interface AgentGuardrails {
+    /**
+     * Screening applied to what reaches the model.
+     *
+     *     There is deliberately no bundle or preset-group member. A named group that expands to a set of checks
+     *     reads like convenience and behaves like version skew: the same agent definition would mean different
+     *     things before and after a platform release, invisibly to the tenant who published it. Listing the checks
+     *     costs a few lines in a document the console writes anyway, and the published version then states exactly
+     *     what it enforces.
+     * @public
+     */
+    input?: AgentGuardrailInput | undefined;
+}
 /**
  * Reference to a skill attached to an agent.
  * @public
@@ -2298,15 +2587,12 @@ export interface AgentWorkflowStep {
      */
     id: string;
     /**
-     * Human readable name of a step, shown in the builder and in traces. Never a routing key — see AgentWorkflowStepId — but it is read by the model as the fallback preview of an exit that leads here when the step carries no `summary`.
+     * Human readable name of a step, e.g. 'Transfer to the sales desk'. Shown in the builder and in traces, and
+     *     read by the model too: when this step is an exit of the live step, the label is the preview offered alongside
+     *     the exit's condition. Never a routing key — see AgentWorkflowStepId — so renaming one never unwires a graph.
      * @public
      */
     label: string;
-    /**
-     * One line saying what happens here, shown to the model as the preview of any exit that leads to this step.
-     * @public
-     */
-    summary?: string | undefined;
     /**
      * The phase this step belongs to. Inherited by steps downstream, so a handful of tags organise a long graph.
      * @public
@@ -2425,6 +2711,15 @@ export interface AgentAiEngine {
      * @public
      */
     workflow?: AgentWorkflow | undefined;
+    /**
+     * Screening applied to a turn before this agent's model sees it. Sits next to `instructions` and
+     *         `workflow` because it is the third thing that governs a session, and it is enforced outside the prompt
+     *         on purpose: a refusal written into `instructions` is one the caller can argue the agent out of.
+     *         Optional — absent means no screening, which is what every agent authored before guardrails existed
+     *         keeps doing. See AgentGuardrails.
+     * @public
+     */
+    guardrails?: AgentGuardrails | undefined;
     /**
      * Defaults to the platform default model when omitted.
      * @public

package/dist-types/schemas/schemas_0.d.ts

@@ -22,6 +22,15 @@ export declare var AgentConnectorCapability$: StaticStructureSchema;
 export declare var AgentDefinitionSnapshot$: StaticStructureSchema;
 export declare var AgentDelegationCapability$: StaticStructureSchema;
 export declare var AgentDeploymentRoute$: StaticStructureSchema;
+export declare var AgentGuardrailBlockAction$: StaticStructureSchema;
+export declare var AgentGuardrailCheck$: StaticStructureSchema;
+export declare var AgentGuardrailCustomCheck$: StaticStructureSchema;
+export declare var AgentGuardrailEndAction$: StaticStructureSchema;
+export declare var AgentGuardrailInput$: StaticStructureSchema;
+export declare var AgentGuardrailObserveAction$: StaticStructureSchema;
+export declare var AgentGuardrailPresetCheck$: StaticStructureSchema;
+export declare var AgentGuardrailRedactAction$: StaticStructureSchema;
+export declare var AgentGuardrails$: StaticStructureSchema;
 export declare var AgentHandoverCapability$: StaticStructureSchema;
 export declare var AgentHandoverPipeline$: StaticStructureSchema;
 export declare var AgentHangupCapability$: StaticStructureSchema;
@@ -138,6 +147,8 @@ export declare var AgentSkillReference$: StaticStructureSchema;
 export declare var AgentCapability$: StaticUnionSchema;
 export declare var AgentEngine$: StaticUnionSchema;
 export declare var AgentGrantPrincipal$: StaticUnionSchema;
+export declare var AgentGuardrailAction$: StaticUnionSchema;
+export declare var AgentGuardrailCheckKind$: StaticUnionSchema;
 export declare var AgentSandboxCapability$: StaticUnionSchema;
 export declare var AgentToolAnnotation$: StaticUnionSchema;
 export declare var AgentToolFieldHandler$: StaticUnionSchema;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@wildix/wilma-agents-client",
     "description": "@wildix/wilma-agents-client client",
-    "version": "1.0.27",
+    "version": "1.0.28",
     "scripts": {
         "build": "concurrently 'yarn:build:cjs' 'yarn:build:es' 'yarn:build:types'",
         "build:cjs": "tsc -p tsconfig.cjs.json",