@alfadocs/ui-kit 0.68.0 → 0.70.0

package/dist/agent/types.d.ts

@@ -1,12 +1,50 @@
-/** Closed safety vocabulary — drives confirmation UX in the future runtime. */
-export declare const SAFETY_CLASSES: readonly ["read", "write", "destructive"];
+/**
+ * Closed safety vocabulary — drives confirmation UX in the future runtime.
+ *
+ * `phi` marks an action that reads-back-into or WRITES Protected Health
+ * Information (patient-identifiable clinical/contact/financial data). It is
+ * distinct from `write` so the host can gate PHI mutations behind stricter
+ * confirmation + audit than ordinary view-config writes — see
+ * `src/docs/26-agent-readiness.mdx` §PHI. Added 2026-06-24 (DS-owner approved)
+ * for `PatientDetails.update_field`.
+ */
+export declare const SAFETY_CLASSES: readonly ["read", "write", "destructive", "phi"];
 export type Safety = (typeof SAFETY_CLASSES)[number];
 /**
  * Closed capability vocabulary. Adding a capability requires a DS-maintainer
  * approval + an entry in `src/docs/26-agent-readiness.mdx`.
  */
-export declare const CAPABILITIES: readonly ["select_single", "select_multiple", "range_pick", "pick", "filter", "sort", "paginate", "expand", "edit_inline", "navigate", "submit", "dismiss", "open", "close", "view_change", "range_navigate"];
+export declare const CAPABILITIES: readonly ["select_single", "select_multiple", "range_pick", "pick", "filter", "sort", "paginate", "expand", "edit_inline", "set_value", "navigate", "submit", "dismiss", "confirm", "capture", "copy", "scroll", "open", "close", "view_change", "range_navigate"];
 export type Capability = (typeof CAPABILITIES)[number];
+/**
+ * Canonical mapping from the closed safety vocabulary to MCP tool annotations.
+ * A future MCP-server build lifts these verbatim onto each generated tool —
+ * `read` → read-only, `destructive` → destructive, `write` → neither hint.
+ * `phi` is NOT read-only and carries `destructiveHint: true` so the runtime
+ * applies the same confirm-before-act gate as `destructive` — a PHI mutation
+ * is irreversible from the agent's perspective (it changes a patient's record)
+ * and must never be auto-confirmed.
+ * `idempotentHint` / `openWorldHint` are NOT derivable from safety alone and
+ * come from the per-action `idempotent` / `openWorld` fields below.
+ */
+export declare const SAFETY_ANNOTATIONS: {
+    readonly read: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+    };
+    readonly write: {
+        readonly readOnlyHint: false;
+        readonly destructiveHint: false;
+    };
+    readonly destructive: {
+        readonly readOnlyHint: false;
+        readonly destructiveHint: true;
+    };
+    readonly phi: {
+        readonly readOnlyHint: false;
+        readonly destructiveHint: true;
+    };
+};
 /**
  * Externally-observable state slot. `read` is pure and synchronous; async
  * state must be projected through a synchronous snapshot. Returns identifiers
@@ -25,10 +63,44 @@ export interface AgentStateSlot<THandle> {
  * looks up `(adapter.id, instanceId)` in the registry, resolves the handle,
  * and invokes the action.
  */
+export interface AgentActionExample<TArgs = unknown> {
+    /** A concrete argument payload demonstrating a valid call. */
+    args?: TArgs;
+    /** i18n key or literal note explaining the example. */
+    note?: string;
+}
 export interface AgentAction<THandle, TArgs = unknown> {
     safety: Safety;
-    /** Type label for `args` — purely descriptive in v1. */
+    /** Human type label for `args` (e.g. `'{ ids: string[] }'`) — descriptive. */
     argsType?: string;
+    /**
+     * Machine-readable JSON Schema for `args`. This is what a future MCP server
+     * lifts into the tool's `inputSchema`. When present it is the source of truth;
+     * `argsType` remains the human label. Omit for no-arg actions.
+     */
+    argsSchema?: Record<string, unknown>;
+    /** Human type label for the value `invoke` resolves to (e.g. `'string[]'`). */
+    returns?: string;
+    /** JSON Schema for the resolved value — maps to an MCP tool `outputSchema`. */
+    returnsSchema?: Record<string, unknown>;
+    /**
+     * True when calling twice with the same args has the same effect as calling
+     * once (e.g. `set_value`, `go_to_page`). Maps to MCP `idempotentHint`.
+     */
+    idempotent?: boolean;
+    /**
+     * True when the action reaches a system outside this UI (server write,
+     * external fetch, clipboard). Maps to MCP `openWorldHint`.
+     */
+    openWorld?: boolean;
+    /** Expected failure modes the MCP server can pre-declare (free-text hints). */
+    errors?: string[];
+    /** Example calls — improve an LLM's first-try tool-call accuracy. */
+    examples?: AgentActionExample<TArgs>[];
+    /** Stability tier. Absent ⇒ treated as `stable`. */
+    stability?: 'stable' | 'experimental';
+    /** Deprecation marker — `true`, or a string explaining the replacement. */
+    deprecated?: boolean | string;
     description?: string;
     descriptionKey?: string;
     invoke: (handle: THandle, args: TArgs) => unknown | Promise<unknown>;
@@ -84,6 +156,12 @@ export interface PatternWorkflow {
     safety: Safety;
     /** Adapter actions this workflow invokes, formatted as `"<component-id>.<action>"`. */
     uiActions: string[];
+    /**
+     * Adapter STATE slots this workflow reads, formatted as
+     * `"<component-id>.<slot>"`. Use this instead of inventing a fake action when
+     * a workflow needs to read live state (e.g. `"data-table.selection"`).
+     */
+    stateReads?: string[];
     /** API operations this workflow ultimately calls, formatted as `"<resource>.<verb>"`. */
     apiActions: string[];
 }
@@ -102,12 +180,25 @@ export interface CatalogStateSlot {
     name: string;
     type: string;
     description?: string;
+    /** Carried through so the host can re-resolve in the user's locale at runtime. */
+    descriptionKey?: string;
 }
 export interface CatalogAction {
     name: string;
     safety: Safety;
     argsType?: string;
+    argsSchema?: Record<string, unknown>;
+    returns?: string;
+    returnsSchema?: Record<string, unknown>;
+    idempotent?: boolean;
+    openWorld?: boolean;
+    errors?: string[];
+    examples?: AgentActionExample[];
+    stability?: 'stable' | 'experimental';
+    deprecated?: boolean | string;
     description?: string;
+    /** Carried through so the host can re-resolve in the user's locale at runtime. */
+    descriptionKey?: string;
 }
 export interface CatalogDomHook {
     attr: string;
@@ -135,7 +226,9 @@ export interface CatalogPattern {
         name: string;
         safety: Safety;
         description?: string;
+        descriptionKey?: string;
         uiActions: string[];
+        stateReads?: string[];
         apiActions: string[];
     }>;
 }