@alfadocs/ui-kit 0.68.0 → 0.69.0

package/dist/agent/types.d.ts

@@ -5,8 +5,29 @@ 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.
+ * `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;
+    };
+};
 /**
  * Externally-observable state slot. `read` is pure and synchronous; async
  * state must be projected through a synchronous snapshot. Returns identifiers
@@ -25,10 +46,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 +139,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 +163,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 +209,9 @@ export interface CatalogPattern {
         name: string;
         safety: Safety;
         description?: string;
+        descriptionKey?: string;
         uiActions: string[];
+        stateReads?: string[];
         apiActions: string[];
     }>;
 }