@wippy-fe/types-global-proxy 0.0.58 → 0.0.60

package/index.d.ts

@@ -1,6 +1,6 @@
 import { PanelTree, FloatingAnchor, ModalSize, SizeValue, PanelTarget } from '@wippy-fe/layout';
+import { AttentionConfig, AttentionSubscriptionOptions, AttentionNotification, AttentionSubscription, AttentionInspectionScope, AttentionInspectionResult, AttentionNodeRef, AttentionSearch, AttentionLayoutRegistration, AttentionLayoutHandle, AttentionInspectionCall, AttentionTargetRefV1, ContextAttachmentEnvelope, AttentionUiActionRequestV1, AttentionUiActionResultV1, AttentionRuntimeBootstrapV1, SurfaceApi, GLOBAL_CONFIG_VAR, GLOBAL_API_PROVIDER, GLOBAL_PROXY_CONFIG_VAR, GLOBAL_WEB_COMPONENT_CACHE } from '@wippy-fe/shared';
 import { AxiosDefaults, AxiosInstance } from 'axios';
-import { SurfaceApi, GLOBAL_CONFIG_VAR, GLOBAL_API_PROVIDER, GLOBAL_PROXY_CONFIG_VAR, GLOBAL_WEB_COMPONENT_CACHE } from '@wippy-fe/shared';
 import { ConfirmationOptions } from 'primevue/confirmationoptions';
 import { ToastMessageOptions } from 'primevue/toast';
 import * as nanoevents from 'nanoevents';
@@ -273,6 +273,7 @@ interface ApiRoutes {
         list: string;
         get: string;
         messages: string;
+        context: string;
     };
     models: {
         list: string;
@@ -282,6 +283,7 @@ interface ApiRoutes {
         list: string;
         get: string;
         create: string;
+        delete: string;
     };
     artifacts: {
         get: string;
@@ -640,6 +642,7 @@ interface AppConfig {
     axiosDefaults?: Partial<AxiosDefaults>;
     routePrefix?: string;
     apiRoutes?: ApiRoutesOverride;
+    attention?: AttentionConfig;
     tanstack?: TanstackConfig;
     themeMode?: ThemeMode;
     theming: {
@@ -737,6 +740,78 @@ interface SanitizeOptions {
     extraTags?: Record<string, string[]>;
 }
 
+interface AttentionInspectionApi {
+    subscribe: (options: AttentionSubscriptionOptions, listener: (notification: AttentionNotification) => void) => AttentionSubscription;
+    getCursor: (scope?: AttentionInspectionScope) => Promise<AttentionInspectionResult>;
+    getFocus: (scope?: AttentionInspectionScope) => Promise<AttentionInspectionResult>;
+    getSelection: (scope?: AttentionInspectionScope) => Promise<AttentionInspectionResult>;
+    atPoint: (point: {
+        x: number;
+        y: number;
+        coordinate_space?: 'host-viewport' | AttentionNodeRef;
+        radius_css_px?: number;
+        step_css_px?: number;
+    }, scope?: AttentionInspectionScope) => Promise<AttentionInspectionResult>;
+    getTree: (options?: AttentionInspectionScope & {
+        limit?: number;
+        depth?: number;
+        continuation?: string;
+    }) => Promise<AttentionInspectionResult>;
+    find: (query: AttentionSearch, options?: AttentionInspectionScope & {
+        limit?: number;
+        continuation?: string;
+    }) => Promise<AttentionInspectionResult>;
+    getGeometry: (node: AttentionNodeRef, scope?: AttentionInspectionScope) => Promise<AttentionInspectionResult>;
+}
+
+interface AttentionSemanticLabels {
+    role?: string;
+    name?: string;
+    text?: string;
+}
+
+interface AttentionApi extends AttentionInspectionApi {
+    registerSemantic: (element: Element, labels: AttentionSemanticLabels) => () => void;
+    registerLayoutProvider: (input: AttentionLayoutRegistration) => AttentionLayoutHandle;
+    readonly enabled: boolean;
+    supports: (feature: 'message-context' | 'agent-actions' | 'visual-capture') => boolean;
+    prepareMessageContext: (request: {
+        requestId: string;
+        text: string;
+        sessionId?: string;
+        startToken?: string;
+        attentionContextEnabled?: boolean;
+    }) => Promise<{
+        session_id: string;
+        attention_context?: {
+            enabled: boolean;
+            revision: number;
+        };
+        context_attachments_ref?: unknown;
+        ui_action_intent_nonce?: string;
+    }>;
+    registerComposerDrafts?: (request: AttentionComposerDraftRegistrationRequest) => AttentionComposerDraftRegistration;
+}
+interface AttentionComposerDraftFile {
+    id: string;
+    uuid?: string;
+    filename: string;
+    mime_type: string;
+    size: number;
+    status: 'uploading' | 'ready' | 'error';
+}
+interface AttentionComposerDraftRegistrationRequest {
+    sessionId?: string;
+    visible?: boolean;
+    onChange: (files: AttentionComposerDraftFile[]) => void;
+}
+interface AttentionComposerDraftRegistration {
+    update: (sessionId?: string, visible?: boolean) => void;
+    remove: (id: string) => Promise<void>;
+    commit: (uuids: string[]) => void;
+    dispose: () => void;
+}
+
 interface BridgeRequestOptions {
     timeoutMs?: number;
 }
@@ -781,6 +856,36 @@ declare namespace UploadApi {
         success: boolean;
         uuid: string;
     }
+    interface DeleteResponse {
+        success: boolean;
+    }
+}
+
+interface InspectionControlRequest {
+    schema: 'wippy.ui-action.v1';
+    message_type: 'request';
+    mode: 'inspect';
+    action_id: string;
+    request_id: string;
+    session_id: string;
+    host_instance_id: string;
+    created_at: string;
+    expires_at: string;
+    query: AttentionInspectionCall;
+}
+interface InspectionControlResult {
+    schema: 'wippy.ui-action.v1';
+    message_type: 'result';
+    result_id: string;
+    in_reply_to_action_id: string;
+    request_id: string;
+    session_id: string;
+    host_instance_id: string;
+    completed_at: string;
+    status: 'inspected' | 'unavailable' | 'expired' | 'stale' | 'error';
+    inspection?: AttentionInspectionResult;
+    targets?: AttentionTargetRefV1[];
+    reason?: string;
 }
 
 declare enum ArtifactStatus {
@@ -845,6 +950,15 @@ interface Artifact {
     status: ArtifactStatus;
 }
 
+interface SessionInteraction {
+    can_send: boolean;
+    revision: number;
+}
+interface SessionInput {
+    state: 'pending' | 'applied';
+    after_message_id?: string;
+}
+
 type ArtifactUUID = string;
 type PageUUID = string;
 type SessionUUID = string;
@@ -865,6 +979,7 @@ declare const WsTopicPrefixes: {
     readonly Action: "action";
     readonly Registry: "registry";
     readonly RegistryEntry: "entry";
+    readonly UiActionRequest: "session_ui_action_request";
 };
 interface WsTopicTypes {
     /**
@@ -919,9 +1034,13 @@ interface WsTopicTypes {
      * Upload was created or updated
      */
     Upload: `${typeof WsTopicPrefixes.Upload}:${string}`;
+    /** Agent-requested host overlay action. */
+    UiActionRequest: typeof WsTopicPrefixes.UiActionRequest;
 }
 type WsTopic = WsTopicTypes[keyof WsTopicTypes];
 declare enum WsMessageType {
+    /** Patch an existing message or session. */
+    UPDATE = "update",
     /** Contains the actual content of the message */
     CONTENT = "content",
     /** Contains content of the message to append to current one */
@@ -1038,6 +1157,36 @@ interface WsMessageDataUser extends WsMessageDataBase {
     text: string;
     message_id: MessageUUID;
     file_uuids?: string[];
+    context_attachments?: ContextAttachmentEnvelope[];
+    input?: SessionInput;
+}
+interface WsMessage_UiActionRequest extends WsMessageBase {
+    topic: WsTopicTypes['UiActionRequest'];
+    data: AttentionUiActionRequestV1 | InspectionControlRequest;
+}
+interface WsMessageDataCommandResponse {
+    type: 'command_response';
+    request_id: string;
+    success: boolean;
+    code?: string;
+    message?: string;
+    context_attachments_transport?: {
+        version: number;
+        staging: boolean;
+        max_context_bytes: number;
+    };
+    context_attachments_capabilities?: {
+        version: number;
+        handlers: Array<{
+            kind: string;
+            versions: number[];
+        }>;
+    };
+}
+interface WsMessageDataUpdate extends WsMessageDataBase {
+    type: WsMessageType.UPDATE;
+    message_id: MessageUUID;
+    input: SessionInput;
 }
 interface WsMessageDataDelegation extends WsMessageDataBase {
     type: WsMessageType.DELEGATION;
@@ -1077,27 +1226,36 @@ interface WsMessageDataError extends WsMessageDataBase {
 }
 interface WsMessage_SessionMessage extends WsMessageBase {
     topic: WsTopicTypes['SessionMessage'];
-    data: (WsMessageDataUser | WsMessageDataContent | WsMessageDataChunk | WsMessageDataDelegation | WsMessageDataToolCall | WsMessageDataError | WsMessageDataInvalidate | WsMessageDataStarted | WsMessageDataToolSuccess | WsMessageDataArtifact | WsMessageDataToolError) & {
+    data: (WsMessageDataUser | WsMessageDataContent | WsMessageDataChunk | WsMessageDataDelegation | WsMessageDataToolCall | WsMessageDataError | WsMessageDataInvalidate | WsMessageDataStarted | WsMessageDataToolSuccess | WsMessageDataArtifact | WsMessageDataToolError | WsMessageDataUpdate) & {
         request_id?: string;
     };
 }
 interface WsMessage_Session extends WsMessageBase {
     topic: WsTopicTypes['Session'];
-    data: {
+    data: WsMessageDataCommandResponse | {
         request_id?: string;
+        session_id?: SessionUUID;
         agent?: string;
         last_message_date?: number;
         model?: string;
         status?: string;
         title?: string;
         type: 'update';
+        interaction?: SessionInteraction;
         public_meta?: Array<{
             icon?: string;
             id: string;
             title: string;
             url?: string;
         }>;
-    };
+        attention_context?: {
+            enabled: boolean;
+            revision: number;
+        };
+    } | (WsMessageDataError & {
+        request_id?: string;
+        session_id?: SessionUUID;
+    });
 }
 interface WsMessage_Artifact extends WsMessageBase {
     topic: WsTopicTypes['Artifact'];
@@ -1111,8 +1269,14 @@ interface WsMessage_Upload extends WsMessageBase {
         request_id?: string;
     };
 }
-type WsMessage = WsMessage_Welcome | WsMessage_Pages | WsMessage_Page | WsMessage_SessionMessage | WsMessage_Session | WsMessage_SessionClosed | WsMessage_Error | WsMessage_Artifact | WsMessage_SessionOpen | WsMessage_Action | WsMessage_Registry | WsMessage_RegistryEntry | WsMessage_Upload;
+type WsMessage = WsMessage_Welcome | WsMessage_Pages | WsMessage_Page | WsMessage_SessionMessage | WsMessage_Session | WsMessage_SessionClosed | WsMessage_Error | WsMessage_Artifact | WsMessage_SessionOpen | WsMessage_Action | WsMessage_UiActionRequest | WsMessage_Registry | WsMessage_RegistryEntry | WsMessage_Upload;
 
+interface ContextAttachmentsReference {
+    version: 1;
+    id: string;
+    content_hash: string;
+    content_bytes: number;
+}
 interface BaseWsCommand {
     type: string;
     /**
@@ -1124,6 +1288,7 @@ interface SessionOpenCommand extends BaseWsCommand {
     type: 'session_open';
     session_id?: string;
     start_token?: string;
+    attention_context_enabled?: boolean;
 }
 interface SessionCloseCommand extends BaseWsCommand {
     type: 'session_close';
@@ -1132,10 +1297,19 @@ interface SessionCloseCommand extends BaseWsCommand {
 interface SessionMessageCommand extends BaseWsCommand {
     type: 'session_message';
     session_id: string;
-    message_id: string;
+    /** Legacy fire-and-forget servers require this client-generated ID. */
+    message_id?: string;
     data: {
         text: string;
         file_uuids?: string[];
+        context_attachments?: ContextAttachmentEnvelope[];
+        context_attachments_ref?: ContextAttachmentsReference;
+        runtime_context?: {
+            attention?: {
+                host_instance_id: string;
+                agent_actions_enabled: boolean;
+            };
+        };
     };
 }
 interface SessionCommandCommand extends BaseWsCommand {
@@ -1143,6 +1317,11 @@ interface SessionCommandCommand extends BaseWsCommand {
     session_id: string;
     data: StopCommand | ModelCommand | OtherCommand | AgentCommand;
 }
+interface UiActionResultCommand extends BaseWsCommand {
+    type: 'session_ui_action_result';
+    session_id: string;
+    data: AttentionUiActionResultV1 | InspectionControlResult;
+}
 interface StopCommand {
     command: 'stop';
 }
@@ -1162,7 +1341,7 @@ interface OtherCommand {
     command: string;
     [key: string]: unknown;
 }
-type WsCommand = SessionOpenCommand | SessionCloseCommand | SessionMessageCommand | SessionCommandCommand | ExternalEventCommand;
+type WsCommand = SessionOpenCommand | SessionCloseCommand | SessionMessageCommand | SessionCommandCommand | UiActionResultCommand | ExternalEventCommand;
 
 /**
  * Read-only mirror of the current host `HostLayoutDeclaration`, minus
@@ -1322,6 +1501,7 @@ interface HtmlInjectOptions {
     isNavOwner?: boolean;
     configOverrides?: AppConfigOverrides;
     proxyConfig?: ProxyConfig;
+    attentionBootstrap?: AttentionRuntimeBootstrapV1;
 }
 interface ProxyHtmlApi {
     inject: (sourceHtml: string, options?: HtmlInjectOptions) => Promise<string>;
@@ -1433,6 +1613,7 @@ interface FormResult {
 type LimitedConfirmationOptions = Omit<ConfirmationOptions, 'target' | 'appendTo' | 'onShow' | 'onHide'>;
 interface ProxyApiInstance {
     config: ChildAppConfig;
+    attention: AttentionApi;
     /** @deprecated, use `host` instead */
     iframe: {
         toast: (message: ToastMessageOptions) => void;
@@ -1599,6 +1780,7 @@ declare global {
             config: () => Promise<ChildAppConfig>;
             instance: () => Promise<ProxyApiInstance>;
             api: () => Promise<ProxyApiInstance['api']>;
+            attention: () => Promise<ProxyApiInstance['attention']>;
             /** @deprecated Use `$W.api` instead */
             form: () => Promise<ProxyApiInstance['api']>;
             host: () => Promise<ProxyApiInstance['host']>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wippy-fe/types-global-proxy",
-  "version": "0.0.58",
+  "version": "0.0.60",
   "description": "Global type declarations for Wippy iframe proxy (window.getWippyApi, $W, etc.)",
   "license": "UNLICENSED",
   "types": "index.d.ts",