@proteos/component-sdk 0.60.0 → 0.75.0

package/src/context.tsx

@@ -6,21 +6,27 @@ import type {
   FunctionsClient,
   KnowledgeClient,
   MetaClient,
+  PageAction,
   StorageClient,
 } from '@proteos/sdk'
 import { createContext, type ReactNode, useMemo } from 'react'
 
 import {
+  type CloseAgentWindowMessage,
   type Envelope,
   isHostMessage,
   MESSAGE_SOURCE,
   type ModalResultMessage,
   type ModalWidth,
   type NavigateMessage,
+  type OpenAgentWindowMessage,
   type OpenCallMessage,
   type OpenModalMessage,
   type OpenPeekMessage,
+  type PageActionContext,
+  type PageActionOutcome,
   type PageContext,
+  type RunPageActionMessage,
 } from './protocol'
 
 /** Options for {@link RuntimeContextValue.navigate}. */
@@ -45,6 +51,33 @@ export interface OpenModalOptions {
   height?: number
 }
 
+/** What {@link AgentWindowController.open} opens the host's agent window to. */
+export interface OpenAgentWindowOptions {
+  /** Resume this session (its agent comes with it). */
+  sessionId?: string
+  /** Start a fresh session with this agent. Ignored when `sessionId` is set,
+   *  and when the host surface pins its agent. Without it (and without a
+   *  session) the window's currently selected agent is used. */
+  agentKey?: string
+  /** A message to send — into the resumed session, or as the first message
+   *  of the fresh one. */
+  prompt?: string
+  /** Context handed to the model alongside `prompt` (what the component knows:
+   *  the record on screen, a selection …). Read by the model, never shown in
+   *  the chat; sent only together with a `prompt`. Not for secrets. */
+  context?: string
+}
+
+/**
+ * The host's agent session window (the floating assistant), driven from a
+ * component. `open()` posts OPEN_AGENT_WINDOW, `close()` posts
+ * CLOSE_AGENT_WINDOW — closing minimizes; the session and its stream live on.
+ */
+export interface AgentWindowController {
+  open: (options?: OpenAgentWindowOptions) => void
+  close: () => void
+}
+
 /**
  * Manual control over iframe overlay promotion. The runtime already detects
  * overlays automatically (anything portaled to the iframe's `document.body` —
@@ -130,6 +163,12 @@ export interface RuntimeContextValue extends RuntimeValue {
     props?: Record<string, unknown>,
     options?: OpenModalOptions,
   ) => Promise<unknown>
+  /** Open / minimize the host's agent session window (posts OPEN_AGENT_WINDOW
+   *  / CLOSE_AGENT_WINDOW). */
+  agentWindow: AgentWindowController
+  /** Run a page action defined inline (posts RUN_PAGE_ACTION); resolves with
+   *  how its flow ended. */
+  runPageAction: (action: PageAction, context?: PageActionContext) => Promise<PageActionOutcome>
 }
 
 export const RuntimeContext = createContext<RuntimeContextValue | null>(null)
@@ -158,30 +197,65 @@ function openCall(conversationBriefId: string): void {
   window.parent?.postMessage(envelope, '*')
 }
 
+/** Post OPEN_AGENT_WINDOW — only the fields that were given ride the wire. */
+function openAgentWindow(options?: OpenAgentWindowOptions): void {
+  const envelope: Envelope<OpenAgentWindowMessage> = {
+    source: MESSAGE_SOURCE,
+    type: 'OPEN_AGENT_WINDOW',
+    ...(options?.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+    ...(options?.agentKey !== undefined ? { agentKey: options.agentKey } : {}),
+    ...(options?.prompt !== undefined ? { prompt: options.prompt } : {}),
+    ...(options?.context !== undefined ? { context: options.context } : {}),
+  }
+  window.parent?.postMessage(envelope, '*')
+}
+
+/** Post CLOSE_AGENT_WINDOW — minimize the host's agent window. */
+function closeAgentWindow(): void {
+  const envelope: Envelope<CloseAgentWindowMessage> = {
+    source: MESSAGE_SOURCE,
+    type: 'CLOSE_AGENT_WINDOW',
+  }
+  window.parent?.postMessage(envelope, '*')
+}
+
+const agentWindow: AgentWindowController = { open: openAgentWindow, close: closeAgentWindow }
+
 /** Navigate full-page (default) or into a peek panel (`{ peek: true }`). */
 function navigate(to: string, options?: NavigateOptions): void {
   if (options?.peek) postOpenPeek(to)
   else postNavigate(to)
 }
 
-// ── Component modals ────────────────────────────────────────────────────────
-// One module-level listener + a pending map, rather than a listener per call:
-// the SDK is an import-mapped singleton, so this is per-iframe state.
+// ── Host requests (component modals, page actions) ──────────────────────────
+// One module-level listener + a pending map per request kind, rather than a
+// listener per call: the SDK is an import-mapped singleton, so this is
+// per-iframe state.
 
 const pendingModals = new Map<string, (result: unknown) => void>()
-let modalListenerAttached = false
+const pendingPageActions = new Map<string, (outcome: PageActionOutcome) => void>()
+let replyListenerAttached = false
 
-function ensureModalListener(): void {
-  if (modalListenerAttached) return
-  modalListenerAttached = true
+function ensureReplyListener(): void {
+  if (replyListenerAttached) return
+  replyListenerAttached = true
   window.addEventListener('message', (event: MessageEvent) => {
     const data: unknown = event.data
-    if (!isHostMessage(data) || data.type !== 'MODAL_CLOSED') return
-    const resolve = pendingModals.get(data.requestId)
-    // An unknown requestId is someone else's modal (or a stale reply) — drop it.
-    if (!resolve) return
-    pendingModals.delete(data.requestId)
-    resolve(data.result)
+    if (!isHostMessage(data)) return
+    // An unknown requestId is someone else's request (or a stale reply) — drop it.
+    if (data.type === 'MODAL_CLOSED') {
+      const resolve = pendingModals.get(data.requestId)
+      if (!resolve) return
+      pendingModals.delete(data.requestId)
+      resolve(data.result)
+      return
+    }
+    if (data.type === 'PAGE_ACTION_SETTLED') {
+      const resolve = pendingPageActions.get(data.requestId)
+      if (!resolve) return
+      pendingPageActions.delete(data.requestId)
+      resolve(data.outcome)
+    }
   })
 }
 
@@ -224,7 +298,7 @@ function newRequestId(): string {
   if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
     return crypto.randomUUID()
   }
-  return `modal_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`
+  return `request_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`
 }
 
 /** Post OPEN_MODAL and resolve when the host answers MODAL_CLOSED. */
@@ -233,7 +307,7 @@ function openModal(
   props?: Record<string, unknown>,
   options?: OpenModalOptions,
 ): Promise<unknown> {
-  ensureModalListener()
+  ensureReplyListener()
   const requestId = newRequestId()
   const envelope: Envelope<OpenModalMessage> = {
     source: MESSAGE_SOURCE,
@@ -255,6 +329,32 @@ function openModal(
   })
 }
 
+/** Post RUN_PAGE_ACTION and resolve when the host answers PAGE_ACTION_SETTLED.
+ *  The host's dialogs take focus, so it goes back to the pressed control
+ *  afterwards — as for a modal. */
+function runPageAction(
+  action: PageAction,
+  context?: PageActionContext,
+): Promise<PageActionOutcome> {
+  ensureReplyListener()
+  const requestId = newRequestId()
+  const envelope: Envelope<RunPageActionMessage> = {
+    source: MESSAGE_SOURCE,
+    type: 'RUN_PAGE_ACTION',
+    requestId,
+    action,
+    ...(context !== undefined ? { context } : {}),
+  }
+  const opener = document.activeElement instanceof HTMLElement ? document.activeElement : null
+  return new Promise<PageActionOutcome>((resolve) => {
+    pendingPageActions.set(requestId, (outcome) => {
+      restoreFocus(opener)
+      resolve(outcome)
+    })
+    window.parent?.postMessage(envelope, '*')
+  })
+}
+
 /** Post MODAL_RESULT — the component inside a host modal closing with a value. */
 export function postModalResult(requestId: string, result?: unknown): void {
   const envelope: Envelope<ModalResultMessage> = {
@@ -278,7 +378,7 @@ export function RuntimeProvider({ value, children }: { value: RuntimeValue; chil
   // props and pageCtx are all set once), so memoizing on its identity recreates
   // the context only when the runtime genuinely re-inits.
   const ctx = useMemo<RuntimeContextValue>(
-    () => ({ ...value, navigate, openCall, openModal }),
+    () => ({ ...value, navigate, openCall, openModal, agentWindow, runPageAction }),
     [value],
   )
   return <RuntimeContext.Provider value={ctx}>{children}</RuntimeContext.Provider>

package/src/hooks.test.tsx

@@ -4,17 +4,24 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import { RuntimeProvider, type RuntimeValue } from './context'
 import {
+  useAgentWindow,
   useApiBaseUrl,
   useComponentModal,
   useModalHost,
   useNavigate,
   useOverlayExpansion,
+  usePageAction,
   usePageContext,
   useProps,
   useRuntime,
   useSdk,
 } from './hooks'
-import { type Envelope, MESSAGE_SOURCE, type ModalClosedMessage } from './protocol'
+import {
+  type Envelope,
+  MESSAGE_SOURCE,
+  type ModalClosedMessage,
+  type PageActionSettledMessage,
+} from './protocol'
 
 // A stable stand-in for the injected SDK — the hooks only pass it through.
 const sdk = {} as RuntimeValue['sdk']
@@ -23,7 +30,7 @@ function makeValue(overrides: Partial<RuntimeValue> = {}): RuntimeValue {
   return {
     sdk,
     props: { title: 'Hello' },
-    pageCtx: { record: { id: 'rec_1', name: 'ACME' }, entity: { slug: 'company' } },
+    pageCtx: { record: { id: 'rec_1', name: 'ACME' }, entity: { slug: 'company' }, mode: 'view' },
     apiBaseUrl: 'https://api.test',
     getToken: () => 'tok_123',
     ...overrides,
@@ -56,11 +63,12 @@ describe('runtime hooks', () => {
     expect(result.current.props.title).toBe('Hello')
     expect(result.current.ctx.record).toEqual({ id: 'rec_1', name: 'ACME' })
     expect(result.current.ctx.entity?.slug).toBe('company')
+    expect(result.current.ctx.mode).toBe('view')
     expect(result.current.base).toBe('https://api.test')
   })
 
   it('usePageContext().record is undefined when the page has no bound record', () => {
-    const value = makeValue({ pageCtx: { entity: { slug: 'dashboard' } } })
+    const value = makeValue({ pageCtx: { entity: { slug: 'dashboard' }, mode: 'view' } })
     const { result } = renderHook(() => usePageContext(), { wrapper: wrapper(value) })
     expect(result.current.record).toBeUndefined()
   })
@@ -75,6 +83,52 @@ describe('runtime hooks', () => {
     )
   })
 
+  it('useAgentWindow posts OPEN_AGENT_WINDOW with only the fields given, and CLOSE_AGENT_WINDOW', () => {
+    const post = vi.spyOn(window.parent, 'postMessage').mockImplementation(() => {})
+    const { result } = renderHook(() => useAgentWindow(), { wrapper: wrapper(makeValue()) })
+
+    result.current.open()
+    expect(post).toHaveBeenLastCalledWith(
+      { source: MESSAGE_SOURCE, type: 'OPEN_AGENT_WINDOW' },
+      '*',
+    )
+
+    result.current.open({ sessionId: 'sess_1', prompt: 'Summarize this' })
+    expect(post).toHaveBeenLastCalledWith(
+      {
+        source: MESSAGE_SOURCE,
+        type: 'OPEN_AGENT_WINDOW',
+        sessionId: 'sess_1',
+        prompt: 'Summarize this',
+      },
+      '*',
+    )
+
+    result.current.open({ agentKey: 'sales-bot' })
+    expect(post).toHaveBeenLastCalledWith(
+      { source: MESSAGE_SOURCE, type: 'OPEN_AGENT_WINDOW', agentKey: 'sales-bot' },
+      '*',
+    )
+
+    result.current.open({ agentKey: 'sales-bot', prompt: 'Follow up', context: 'Deal #7' })
+    expect(post).toHaveBeenLastCalledWith(
+      {
+        source: MESSAGE_SOURCE,
+        type: 'OPEN_AGENT_WINDOW',
+        agentKey: 'sales-bot',
+        prompt: 'Follow up',
+        context: 'Deal #7',
+      },
+      '*',
+    )
+
+    result.current.close()
+    expect(post).toHaveBeenLastCalledWith(
+      { source: MESSAGE_SOURCE, type: 'CLOSE_AGENT_WINDOW' },
+      '*',
+    )
+  })
+
   it('useOverlayExpansion drives the shell controller', () => {
     const overlay = { expand: vi.fn(), collapse: vi.fn(), isExpanded: () => true }
     const { result } = renderHook(() => useOverlayExpansion(), {
@@ -153,6 +207,65 @@ describe('runtime hooks', () => {
     opener.remove()
   })
 
+  it('usePageAction posts RUN_PAGE_ACTION and resolves with the matching outcome', async () => {
+    const post = vi.spyOn(window.parent, 'postMessage').mockImplementation(() => {})
+    const { result } = renderHook(() => usePageAction(), { wrapper: wrapper(makeValue()) })
+    const action = {
+      kind: 'intent' as const,
+      intent: 'update_record' as const,
+      entity: 'deal',
+      label: 'Update deal',
+      icon: 'Sparkles',
+      prompt: 'Apply what was agreed',
+    }
+
+    const pending = result.current(action, {
+      scope: { notes: 'Signed' },
+      records: [{ entitySlug: 'deal', recordId: 'deal_1' }],
+    })
+    const [payload] = post.mock.calls.at(-1) as [Record<string, unknown>]
+    expect(payload).toMatchObject({
+      source: MESSAGE_SOURCE,
+      type: 'RUN_PAGE_ACTION',
+      action,
+      context: {
+        scope: { notes: 'Signed' },
+        records: [{ entitySlug: 'deal', recordId: 'deal_1' }],
+      },
+    })
+
+    const reply = (requestId: string): Envelope<PageActionSettledMessage> => ({
+      source: MESSAGE_SOURCE,
+      type: 'PAGE_ACTION_SETTLED',
+      requestId,
+      outcome: {
+        status: 'done',
+        kind: 'intent',
+        mode: 'update',
+        entitySlug: 'deal',
+        recordId: 'deal_1',
+        title: 'Acme renewal',
+      },
+    })
+    // Another request's reply — and a modal's with our id — must not resolve ours.
+    window.dispatchEvent(new MessageEvent('message', { data: reply('someone-else') }))
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        data: { source: MESSAGE_SOURCE, type: 'MODAL_CLOSED', requestId: payload.requestId },
+      }),
+    )
+    window.dispatchEvent(new MessageEvent('message', { data: reply(payload.requestId as string) }))
+    await expect(pending).resolves.toMatchObject({ status: 'done', recordId: 'deal_1' })
+  })
+
+  it('usePageAction leaves out a context it was not given', () => {
+    const post = vi.spyOn(window.parent, 'postMessage').mockImplementation(() => {})
+    const { result } = renderHook(() => usePageAction(), { wrapper: wrapper(makeValue()) })
+    void result.current({ kind: 'link', url: 'https://example.com', label: 'Open', icon: 'Link' })
+    const [payload] = post.mock.calls.at(-1) as [Record<string, unknown>]
+    expect(payload).not.toHaveProperty('context')
+  })
+
   it('useComponentModal carries the width and height the opener asked for', () => {
     const post = vi.spyOn(window.parent, 'postMessage').mockImplementation(() => {})
     const { result } = renderHook(() => useComponentModal(), { wrapper: wrapper(makeValue()) })

package/src/hooks.ts

@@ -1,6 +1,8 @@
+import type { PageAction } from '@proteos/sdk'
 import { useCallback, useContext, useEffect, useMemo, useState } from 'react'
 
 import {
+  type AgentWindowController,
   type ComponentSdk,
   type NavigateOptions,
   type OpenModalOptions,
@@ -9,7 +11,7 @@ import {
   RuntimeContext,
   type RuntimeContextValue,
 } from './context'
-import type { PageContext } from './protocol'
+import type { PageActionContext, PageActionOutcome, PageContext } from './protocol'
 
 /**
  * Low-level escape hatch: the whole runtime context (sdk, props, pageCtx,
@@ -40,9 +42,13 @@ export function useProps<T extends Record<string, unknown> = Record<string, unkn
 }
 
 /**
- * The full page context: host `record`, `entity`, and URL `params`. The
- * `record` is a snapshot taken at mount (`undefined` on record-less platform
- * pages) — fetch via `useSdk().data` for anything that must stay fresh.
+ * The full page context: host `record`, `entity`, URL `params`, the viewer as
+ * `current_user` (absent on public pages) and the page `mode`
+ * (`'view' | 'create' | 'edit'` — what the viewer is doing with the record).
+ * The `record` is a snapshot taken at mount (`undefined` on record-less
+ * platform pages) — fetch via `useSdk().data` for anything that must stay
+ * fresh. `mode` is a snapshot too: the host remounts the frame when the page
+ * switches between view and edit.
  */
 export function usePageContext(): PageContext {
   return useRuntime().pageCtx
@@ -70,6 +76,26 @@ export function useOpenCall(): (conversationBriefId: string) => void {
   return useRuntime().openCall
 }
 
+/**
+ * Open or minimize the HOST's agent session window (the floating assistant)
+ * from a component — the iframe cannot render it itself.
+ *
+ * ```ts
+ * const agentWindow = useAgentWindow()
+ * agentWindow.open()                                   // just open it
+ * agentWindow.open({ sessionId })                      // resume a session
+ * agentWindow.open({ agentKey: 'sales-bot', prompt })  // fresh session, prompt sent
+ * agentWindow.close()                                  // minimize (session lives on)
+ * ```
+ *
+ * `sessionId` wins over `agentKey` (the session already has an agent); a
+ * `prompt` goes into whichever session the window lands on. Ignored on public
+ * pages, and by preview hosts.
+ */
+export function useAgentWindow(): AgentWindowController {
+  return useRuntime().agentWindow
+}
+
 /** The API origin SDK calls resolve against (for building raw asset URLs). */
 export function useApiBaseUrl(): string {
   return useRuntime().apiBaseUrl
@@ -135,6 +161,45 @@ export function useComponentModal(): (
   return useRuntime().openModal
 }
 
+/**
+ * Run a page action from a component's own button — the very `PageAction` a
+ * page or list toolbar carries, defined inline. The HOST runs it exactly as a
+ * toolbar press: `action` / `workflow` open the invoke dialog, `intent`
+ * prepares a record proposal for review, `agent` opens the agent window,
+ * `link` opens a new tab. Resolves once that flow is over.
+ *
+ * ```ts
+ * const runPageAction = usePageAction()
+ * const outcome = await runPageAction(
+ *   {
+ *     kind: 'intent',
+ *     intent: 'update_record',
+ *     entity: 'deal',
+ *     label: 'Update deal',
+ *     icon: 'Sparkles',
+ *     prompt: 'Apply what was agreed',
+ *     context: '{{ notes }}',
+ *   },
+ *   { scope: { notes }, records: [{ entitySlug: 'deal', recordId: deal.id }] },
+ * )
+ * if (outcome.status === 'done' && outcome.kind === 'intent') refetch()
+ * ```
+ *
+ * The action's Liquid templates render against the page scope (`record`,
+ * `entity`, `params`, `mode`, `current_user`) with `context.scope` merged over
+ * it; `context.records` says what it acts on (default: the page record). See
+ * {@link PageActionContext} and {@link PageActionOutcome}. `visible_when`
+ * still applies — an action whose rule does not match resolves
+ * `unavailable: hidden` without opening anything. One page action at a time;
+ * public pages and previews resolve `unavailable: unsupported`.
+ */
+export function usePageAction(): (
+  action: PageAction,
+  context?: PageActionContext,
+) => Promise<PageActionOutcome> {
+  return useRuntime().runPageAction
+}
+
 export interface ModalHost {
   /** True when this component is rendered as the content of a host modal. */
   isInModal: boolean

package/src/index.ts

@@ -8,8 +8,10 @@
 import './global'
 
 export type {
+  AgentWindowController,
   ComponentSdk,
   NavigateOptions,
+  OpenAgentWindowOptions,
   OpenModalOptions,
   OverlayController,
   RuntimeContextValue,
@@ -18,6 +20,7 @@ export type {
 export { RuntimeProvider } from './context'
 export type { FillViewportOptions, HostLocation, ModalHost } from './hooks'
 export {
+  useAgentWindow,
   useApiBaseUrl,
   useAuthToken,
   useComponentModal,
@@ -27,6 +30,7 @@ export {
   useNavigate,
   useOpenCall,
   useOverlayExpansion,
+  usePageAction,
   usePageContext,
   useProps,
   useRuntime,
@@ -34,6 +38,7 @@ export {
 } from './hooks'
 export {
   type AuthRefreshMessage,
+  type CloseAgentWindowMessage,
   COMPONENT_OVERLAY_Z_INDEX,
   type DataInvalidateMessage,
   type Envelope,
@@ -48,14 +53,22 @@ export {
   type ModalResultMessage,
   type ModalWidth,
   type NavigateMessage,
+  type OpenAgentWindowMessage,
   type OpenCallMessage,
   type OpenModalMessage,
   type OpenPeekMessage,
   type OverlayRect,
   type OverlayRectMessage,
   type OverlayStateMessage,
+  type PageActionContext,
+  type PageActionOutcome,
+  type PageActionRecord,
+  type PageActionSettledMessage,
   type PageContext,
+  type PageMode,
   type ReadyMessage,
   type ResizeMessage,
+  type RunPageActionMessage,
   type RuntimeMessage,
+  type TriggerPhase,
 } from './protocol'