@wildo-ai/saas-models 1.1.4 → 1.1.5

package/dist/esm/requests/websocket.shared.schemas.js

@@ -1,10 +1,11 @@
 import { z } from 'zod';
 import { DataMode } from '../resources/resources-config.shared.schemas.js';
-import { FrontendDisplayHintsSchema } from '../notifications/notifications.shared.schemas.js';
+import { FrontendDisplayHintsSchema, UserNotificationTargetSchema } from '../notifications/notifications.shared.schemas.js';
 import { ValueMomentRole, ValueMomentScope } from '../config/analytics-value-moments.shared.schemas.js';
 import { OnboardingStatus } from '../config/frontend/onboarding.shared.schemas.js';
 import { GuidanceFlowScope, GuidanceRenderMode } from '../guidance/guidance-flow.shared.schemas.js';
-import { ProgressionScope, MilestoneRewardType } from '../guidance/milestone-definition.shared.schemas.js';
+import { CelebrationDisplayMode } from '../notifications/notifications.shared.schemas.js';
+import { MilestoneCelebrationLevel, ProgressionScope, MilestoneRewardType } from '../guidance/milestone-definition.shared.schemas.js';
 import { LifecycleStage, LifecycleScope } from '../guidance/lifecycle-state.shared.schemas.js';
 import { ResourceOperationVariantType } from '../resources/resources.shared.schemas.js';
 import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
@@ -39,6 +40,15 @@ export var CoreWebSocketEvent;
     CoreWebSocketEvent["RESOURCE_UNLOCKED"] = "resource:unlocked";
     CoreWebSocketEvent["RESOURCE_CUSTOM"] = "resource:custom";
     CoreWebSocketEvent["RESOURCE_CUSTOM_ERROR"] = "resource:custom:error";
+    /**
+     * How far a BACKGROUND BULK run has got, sent to the person who started it (server → client).
+     *
+     * Addressed to the USER rather than to a resource room: the run spans many rows, so no row's room
+     * is the right place, and the job's own row is an internal record most people cannot read. The
+     * rows themselves still broadcast their ordinary sync events as they change, so the listing
+     * updates itself; this event is what lets the surface say how much is left (#1461).
+     */
+    CoreWebSocketEvent["BULK_JOB_PROGRESS"] = "bulk-job:progress";
     // === FlowsActors Events (bidirectional) ===
     CoreWebSocketEvent["FLOWS_ACTORS_START"] = "flows-actors:start";
     CoreWebSocketEvent["FLOWS_ACTORS_STARTED"] = "flows-actors:started";
@@ -178,6 +188,11 @@ export const WS_ResourceNotificationPayloadSchema = z.object({
     variantKey: z.string().optional(),
     // Context for scoped matching
     contextResourceIdentifiers: ContextResourceIdentifiersSchema.optional(),
+    /** Server-authored delivery policy. Keep the frame for data refresh even when its message is suppressed. */
+    deliveryPolicy: z.object({
+        target: UserNotificationTargetSchema,
+        alwaysDeliver: z.boolean(),
+    }),
     // Notification data
     action: ResourceActionSchema,
     /** Explicit notification level (overrides action-based default) */
@@ -280,12 +295,25 @@ export const WS_MilestoneAchievedPayloadSchema = z.object({
         type: z.enum(MilestoneRewardType),
         featureRef: z.string().optional(),
         guidanceFlowRef: z.string().optional(),
-        celebrationLevel: z.enum(['low', 'medium', 'high']).optional(),
+        /*
+         * Typed against the named vocabulary rather than the inline union it was — the same correction
+         * the lifecycle fields below record, for the same reason: this payload is what the frontend
+         * derives a presentation from, and an untyped copy of a vocabulary drifts from it in silence.
+         */
+        celebrationLevel: z.enum(MilestoneCelebrationLevel).optional(),
+        /** An explicit presentation, overriding whatever the level would have chosen. */
+        celebrationMode: z.enum(CelebrationDisplayMode).optional(),
     }),
     /** Phase 5 integration: lifecycle transition triggered by this milestone */
+    /**
+     * Typed against the named vocabulary, like `WS_LifecycleStageChangedPayloadSchema` a few
+     * declarations below — these two were `z.string()` while their neighbour used
+     * `z.enum(LifecycleStage)` for the same fact. See `MilestoneLifecycleTransition` for what the
+     * untyped form cost.
+     */
     lifecycleTransition: z.object({
-        from: z.string(),
-        to: z.string(),
+        from: z.enum(LifecycleStage),
+        to: z.enum(LifecycleStage),
     }).optional(),
     /** Timestamp of achievement */
     achievedAt: WebSocketTimestampSchema,
@@ -465,6 +493,57 @@ export const WS_ResourceCustomEventPayloadSchema = z.object({
     // DataMode values match directly: DataMode.RAW === 'raw', etc.
     dataMode: z.enum(DataMode).optional(),
 });
+/**
+ * How far a background bulk run has got.
+ *
+ * `attemptedCount` is what the run was GIVEN, and it never changes during the run — it is the
+ * denominator a progress bar needs. `processedCount` counts rows the run has finished with, whether
+ * they succeeded or were refused, so `processed / attempted` is honest progress rather than a
+ * success rate; `failedCount` is how many of those were refusals.
+ *
+ * `finished` is explicit rather than inferred from `processedCount === attemptedCount`: a run that
+ * ends early — a worker lost, a job that failed outright — would otherwise leave a bar sitting at
+ * 94% forever with nothing to say it had stopped.
+ */
+export const WS_BulkJobProgressPayloadSchema = z.object({
+    jobId: z.string().min(1),
+    resourceType: z.string().min(1),
+    operationIdentifier: z.string().min(1),
+    attemptedCount: z.number().int().min(0),
+    processedCount: z.number().int().min(0),
+    failedCount: z.number().int().min(0),
+    finished: z.boolean(),
+    /**
+     * WHICH rows were refused, and why — sent on the FINAL event only, and capped at
+     * {@link BULK_JOB_REPORTED_FAILURE_LIMIT}.
+     *
+     * A count tells a person something went wrong; it does not tell them what to do. The refusal's
+     * REFERENCE is what does, because it is the thing a locale turns into words and a client branches
+     * on — so the reasons arrive as references and the surface says them in the reader's language.
+     *
+     * Capped because a run may be given thousands of rows and a socket message is not a report: past
+     * the cap, `failedCount` remains exact while the list is a sample. Every refusal is in the job
+     * result regardless, which is the durable record.
+     *
+     * Sent only when finished, deliberately: a list that grew with each progress event would make the
+     * surface re-render its whole failure panel on every row, and a person cannot read a list that is
+     * still moving.
+     */
+    failures: z.array(z.object({
+        resourceId: z.string().min(1),
+        customMessageReference: z.string().optional(),
+        errorType: z.string().optional(),
+    })).optional(),
+    timestamp: WebSocketOptionalTimestampSchema,
+});
+/**
+ * How many individual refusals a finished bulk run reports over the wire.
+ *
+ * 50 is what a person can actually read in a panel before it stops being a summary; the exact count
+ * is always `failedCount`, and the complete list is in the job result. A larger number would make
+ * the message bigger without making it more useful.
+ */
+export const BULK_JOB_REPORTED_FAILURE_LIMIT = 50;
 /** Error response for custom events */
 export const WS_ResourceCustomErrorPayloadSchema = z.object({
     eventName: z.string(),
@@ -551,6 +630,23 @@ export const WS_FlowsActorsApprovalAnnouncementDataSchema = z.object({
      * these gets their schema from the tool declaration.
      */
     toolArgs: z.record(z.string(), z.unknown()).optional(),
+    /**
+     * The gated tool's INPUT SCHEMA, as the `SerializableZodSchema` descriptor `serializeZodSchema`
+     * (`@wildo-ai/zod-decorators`) produces from the tool's own `inputSchema` (#587).
+     *
+     * It exists so an approver who edits the call is shown the tool's fields — which arguments exist,
+     * which are required, which are enumerations — instead of a JSON blob. It is a RENDERING HINT and
+     * never the control: the server re-validates `modifiedToolArgs` against the tool's live schema and
+     * refuses a violation whatever the browser believed, and the descriptor drops refinements (min/max,
+     * patterns) by construction.
+     *
+     * Absent when the tool cannot be resolved from the paused turn. A client that finds a shape it
+     * cannot render as fields falls back to the raw editor rather than to no editor.
+     *
+     * Loose on the wire for the same reason as `toolArgs`: the shape belongs to the descriptor type,
+     * which this transport does not re-validate.
+     */
+    toolInputSchema: z.record(z.string(), z.unknown()).optional(),
     requestedAt: z.string(),
     /** When the pause lapses. Written since #465; it reaches a client only through this block. */
     expiresAt: z.string().optional(),
@@ -561,6 +657,31 @@ export const WS_FlowsActorsApprovalAnnouncementDataSchema = z.object({
      */
     resourceServerInstanceRef: z.string(),
 });
+/**
+ * A TOOL-STATUS announcement, carried in the `data` bag of a `FLOWS_ACTORS_MESSAGE` of type
+ * `PROGRESS` — one per tool CALL while an assistant turn is working.
+ *
+ * It carries FACTS, never words. The server used to send `content: "Looking up your todos…"`,
+ * composed from the tool name by a humanizer: English produced by code, untranslatable, and wrong
+ * for any resource whose identifier is not also its name (#1283,
+ * `.claude/rules/display-text-comes-from-i18n.md`). The person's words are now resolved in the
+ * browser from the label tree — the component's status labels, and the resource's own authored
+ * title — and `content` carries the tool name verbatim, a value rather than a sentence.
+ *
+ * Producer: `ConversationalExecutionBackendService` (`onToolEvent`). Consumer: the flows-actors
+ * view's status line. The A2A plane ignores tool-status frames (they carry no `messageId`).
+ */
+export const WS_FlowsActorsToolStatusDataSchema = z.object({
+    /** Discriminator. The `data` bag carries other kinds of payload on other messages. */
+    toolStatus: z.literal(true),
+    /** The tool being called, as the agent runtime names it. */
+    tool: z.string(),
+    /**
+     * The resource the tool READS, when it is one of the engine's resource-read tools. Lets the
+     * status name the resource through its authored title; absent for every other tool.
+     */
+    readsResourceType: z.string().optional(),
+});
 /** Human approval request (server → client) */
 export const WS_FlowsActorsApprovalRequestPayloadSchema = z.object({
     systemRef: z.string(),
@@ -626,12 +747,104 @@ export const WS_FlowsActorsCompletedPayloadSchema = z.object({
     duration: z.number().optional(), // in ms
 });
 /** Execution error (server → client) */
+/**
+ * Why a flows-actors request reported an error on `FLOWS_ACTORS_ERROR` — from the socket boundary
+ * (an unauthenticated or malformed request) or from the conversational turn itself.
+ *
+ * One named vocabulary, so a client that must BRANCH on a code — the approval surface keeps a refused
+ * modification on screen rather than dropping it (#587) — compares against a member instead of a
+ * string it copied from the producer.
+ */
+export var FlowsActors_ExecutionErrorCode;
+(function (FlowsActors_ExecutionErrorCode) {
+    /** The socket carries no authenticated user, so a conversation cannot be started. */
+    FlowsActors_ExecutionErrorCode["UNAUTHENTICATED"] = "UNAUTHENTICATED";
+    /** The inbound flows-actors payload failed validation. */
+    FlowsActors_ExecutionErrorCode["INVALID_PAYLOAD"] = "INVALID_PAYLOAD";
+    /** The conversation has no resolvable owner scope. */
+    FlowsActors_ExecutionErrorCode["NO_OWNER"] = "NO_OWNER";
+    /** The system has no agentic actor bound to an agent to converse with. */
+    FlowsActors_ExecutionErrorCode["NO_CHAT_ACTOR"] = "NO_CHAT_ACTOR";
+    /** No user message was provided to start the conversation. */
+    FlowsActors_ExecutionErrorCode["EMPTY_INPUT"] = "EMPTY_INPUT";
+    /** The execution record could not be opened. */
+    FlowsActors_ExecutionErrorCode["PERSIST_FAILED"] = "PERSIST_FAILED";
+    /** The assistant failed to produce a response. */
+    FlowsActors_ExecutionErrorCode["AGENT_FAILED"] = "AGENT_FAILED";
+    /**
+     * The approver's edited tool arguments were refused. RECOVERABLE: the approval is still pending and
+     * can be answered again, so a surface must keep it — this is the one code a client branches on.
+     */
+    FlowsActors_ExecutionErrorCode["APPROVAL_MODIFICATION_REJECTED"] = "APPROVAL_MODIFICATION_REJECTED";
+    /** The system is a FLOW system, and conversational execution of flows is not implemented. */
+    FlowsActors_ExecutionErrorCode["FLOW_CONVERSATION_NOT_IMPLEMENTED"] = "FLOW_CONVERSATION_NOT_IMPLEMENTED";
+    /** No actor system is registered under the requested ref. */
+    FlowsActors_ExecutionErrorCode["SYSTEM_NOT_FOUND"] = "SYSTEM_NOT_FOUND";
+    /**
+     * The application requires consent purposes the person has not granted
+     * (`compliance.serviceConsentRequirement.requiredPurposes`), so no turn is started. Terminal for this turn,
+     * and cured by the person recording their consent in their own preferences — the same refusal every other
+     * user-initiated surface answers (#534).
+     */
+    FlowsActors_ExecutionErrorCode["SERVICE_CONSENT_REQUIRED"] = "SERVICE_CONSENT_REQUIRED";
+    /**
+     * CLIENT-DETECTED — no server emits it. The socket that started this turn dropped before the turn
+     * ended. A turn's events are emitted to the socket that started it, so after a drop none of them can
+     * arrive, whether the server went away (a restart) or only the connection did; without this the turn
+     * stays `STARTING` / `RUNNING` forever and the composer never comes back (#1464, 2026-09-24).
+     * RECOVERABLE: when the server survived, the turn still completes and is persisted, and the thread's
+     * own history carries the reply.
+     */
+    FlowsActors_ExecutionErrorCode["CONNECTION_LOST"] = "CONNECTION_LOST";
+})(FlowsActors_ExecutionErrorCode || (FlowsActors_ExecutionErrorCode = {}));
+/**
+ * Why the server refused an approver's EDIT to a tool call's arguments (#1186).
+ *
+ * The refusal used to travel as English prose in `errorMessage`, which the approval card printed after a
+ * localized prefix — untranslatable, and the one place on the card a person read a server sentence. Each
+ * member is a different diagnosis with a different remedy, so the card renders a label per member; the
+ * prose stays in `errorMessage` for logs.
+ */
+export var FlowsActors_ApprovalModificationRefusalReason;
+(function (FlowsActors_ApprovalModificationRefusalReason) {
+    /** The agent that raised the approval is no longer registered, so nothing can check the arguments. */
+    FlowsActors_ApprovalModificationRefusalReason["AGENT_NOT_REGISTERED"] = "agent_not_registered";
+    /** The agent no longer declares the tool the approval names. */
+    FlowsActors_ApprovalModificationRefusalReason["TOOL_NOT_DECLARED"] = "tool_not_declared";
+    /** The tool no longer requires approval, so the pending decision is stale. */
+    FlowsActors_ApprovalModificationRefusalReason["TOOL_NO_LONGER_GATED"] = "tool_no_longer_gated";
+    /** The edited arguments fail the tool's own input schema; `argumentPaths` names the offending ones. */
+    FlowsActors_ApprovalModificationRefusalReason["ARGUMENTS_INVALID"] = "arguments_invalid";
+    /** The approval-signing key is not configured, so a modified call cannot be re-bound. */
+    FlowsActors_ApprovalModificationRefusalReason["SIGNING_KEY_NOT_CONFIGURED"] = "signing_key_not_configured";
+    /** The paused turn's resume payload does not contain the call the approval names. */
+    FlowsActors_ApprovalModificationRefusalReason["CALL_NOT_REWRITABLE"] = "call_not_rewritable";
+})(FlowsActors_ApprovalModificationRefusalReason || (FlowsActors_ApprovalModificationRefusalReason = {}));
+/**
+ * The structured half of an `APPROVAL_MODIFICATION_REJECTED` error: what the card needs to say, in labels.
+ * `reason` is a {@link FlowsActors_ApprovalModificationRefusalReason} member, kept a STRING on the wire for
+ * the same reason `errorCode` is — a client older than a new reason must still parse the payload.
+ */
+export const WS_FlowsActorsApprovalModificationRefusalSchema = z.object({
+    reason: z.string(),
+    /** The tool the approval names, for the reasons that mention it. */
+    toolName: z.string().optional(),
+    /** The argument paths the tool's schema refused — names only, never the values the approver typed. */
+    argumentPaths: z.array(z.string()).optional(),
+});
 export const WS_FlowsActorsErrorPayloadSchema = z.object({
     systemRef: z.string(),
     executionId: z.string(),
+    /**
+     * A {@link FlowsActors_ExecutionErrorCode} member. Kept a STRING on the wire so a client built
+     * before a code was added still parses the payload; producers emit the enum and consumers compare
+     * against it.
+     */
     errorCode: z.string(),
     errorMessage: z.string(),
     recoverable: z.boolean().default(false),
+    /** Present on `APPROVAL_MODIFICATION_REJECTED`: the refusal as labels can say it (#1186). */
+    approvalModificationRefusal: WS_FlowsActorsApprovalModificationRefusalSchema.optional(),
 });
 // =====================================================
 // System Payloads
@@ -684,6 +897,7 @@ export const WebSocketEventSchemas = {
     [CoreWebSocketEvent.RESOURCE_LOCKED]: WS_ResourceRoomStatePayloadSchema,
     [CoreWebSocketEvent.RESOURCE_UNLOCKED]: WS_ResourceRoomStatePayloadSchema,
     [CoreWebSocketEvent.RESOURCE_CUSTOM]: WS_ResourceCustomEventPayloadSchema,
+    [CoreWebSocketEvent.BULK_JOB_PROGRESS]: WS_BulkJobProgressPayloadSchema,
     [CoreWebSocketEvent.RESOURCE_CUSTOM_ERROR]: WS_ResourceCustomErrorPayloadSchema,
     // FlowsActors
     [CoreWebSocketEvent.FLOWS_ACTORS_START]: WS_FlowsActorsStartPayloadSchema,