@fiodos/web-core 0.1.11 → 0.1.14

package/dist/cjs/adapters/webCredentialAutofillAdapter.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Web implementation of @fiodos/core's CredentialAutofillAdapter, on top of
+ * the Credential Management API (`navigator.credentials.get({ password: true,
+ * mediation: 'required' })`). The BROWSER owns the account-picker / user
+ * verification UI; this module only receives the outcome:
+ *
+ * - A `PasswordCredential` → 'success' with the saved username + password.
+ * - `null` (user dismissed the picker, or no saved credential and the browser
+ *   chose not to prompt) → 'dismissed' (graceful fallback, never an error).
+ * - No API / SecurityError (insecure context, iframe policy) → 'unavailable'.
+ *
+ * The credentials never touch storage, logs or the network from here: they go
+ * straight into the app's own login handler parameters, one call, then gone.
+ */
+import type { CredentialAutofillAdapter } from '@fiodos/core';
+export declare function createWebCredentialAutofillAdapter(): CredentialAutofillAdapter;

package/dist/cjs/adapters/webCredentialAutofillAdapter.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWebCredentialAutofillAdapter = createWebCredentialAutofillAdapter;
+function credentialsContainer() {
+    if (typeof navigator === 'undefined')
+        return null;
+    const nav = navigator;
+    return nav.credentials && typeof nav.credentials.get === 'function' ? nav.credentials : null;
+}
+function passwordCredentialSupported() {
+    if (typeof window === 'undefined')
+        return false;
+    const w = window;
+    // The Credential Management password store needs both the constructor and a
+    // secure context; feature-detect instead of sniffing the browser.
+    return typeof w.PasswordCredential === 'function' && w.isSecureContext !== false;
+}
+function createWebCredentialAutofillAdapter() {
+    return {
+        isSupported() {
+            return credentialsContainer() !== null && passwordCredentialSupported();
+        },
+        async requestCredentials() {
+            const container = credentialsContainer();
+            if (!container || !passwordCredentialSupported())
+                return { status: 'unavailable' };
+            let raw;
+            try {
+                // mediation 'required': ALWAYS show the browser's account picker — the
+                // user explicitly asked to sign in, so a visible, cancellable choice is
+                // the honest UX (and the only one that lets them pick among accounts).
+                raw = await container.get({ password: true, mediation: 'required' });
+            }
+            catch {
+                // SecurityError (permissions policy / insecure frame), NotSupportedError…
+                return { status: 'unavailable' };
+            }
+            const cred = raw;
+            if (!cred)
+                return { status: 'dismissed' };
+            if (cred.type === 'password' && cred.id && typeof cred.password === 'string' && cred.password) {
+                return { status: 'success', username: cred.id, password: cred.password };
+            }
+            return { status: 'unavailable' };
+        },
+    };
+}

package/dist/cjs/api/backendClient.js

@@ -119,6 +119,20 @@ function createFiodosBackendClient(options) {
             if (request.sessionId?.trim()) {
                 body.session_id = request.sessionId.trim();
             }
+            // Device capability flags (retrocompatible: old backends ignore them).
+            if (request.platformCapabilities?.credentialAutofill) {
+                body.platform_capabilities = { credential_autofill: true };
+            }
+            // Live session verdict for audience filtering (retrocompatible: absent
+            // when the host wired no session source; old backends ignore it).
+            if (request.sessionContext) {
+                body.session_context = {
+                    authenticated: request.sessionContext.authenticated,
+                    ...(request.sessionContext.capabilities
+                        ? { capabilities: request.sessionContext.capabilities }
+                        : {}),
+                };
+            }
             // Autonomous-chain continuation metadata (backward compatible: absent on a
             // normal turn; an old backend simply ignores these fields).
             if (request.isContinuation) {

package/dist/cjs/config/types.d.ts

@@ -3,7 +3,7 @@
  * Mirrors @fiodos/react's FiodosWebAgentConfig (same adapters, same lifecycle).
  * Shared by every framework binding through the AgentController.
  */
-import type { ActionRegistries, AgentBackendClient, AgentMessages, AppManifest, ConfirmationLexicon, MessageCatalog, NavigationAdapter, Sanitizer, StorageAdapter, TelemetryAdapter, VoiceAdapter } from '@fiodos/core';
+import type { ActionRegistries, AgentBackendClient, AgentMessages, AppManifest, ConfirmationLexicon, CredentialAutofillAdapter, MessageCatalog, NavigationAdapter, Sanitizer, StorageAdapter, TelemetryAdapter, VoiceAdapter } from '@fiodos/core';
 import type { ResolveUiMessagesOptions, WebUiMessages } from '../ui/messages';
 export type AgentPhase = 'idle' | 'listening' | 'thinking' | 'speaking' | 'confirming';
 export interface AgentTimings {
@@ -55,7 +55,26 @@ export interface FiodosWebAgentConfig {
     storage: StorageAdapter;
     telemetry?: TelemetryAdapter;
     /** Host auth check, required by manifest actions declaring requiresAuth. */
-    isAuthenticated?: () => boolean;
+    isAuthenticated?: () => boolean | null | undefined;
+    /**
+     * Fine-grained session capability flags from the wired session bridge
+     * (audience map: e.g. { has_payment_method: true }). Sent with each turn so
+     * the backend shows this user only THEIR face of the orb. Boolean flags
+     * only — never user data. null/undefined = unknown (nothing is filtered).
+     */
+    getSessionCapabilities?: () => Record<string, boolean> | null | undefined;
+    /**
+     * Platform saved-credential service powering the built-in SMART SIGN-IN
+     * flow (browser password manager). Defaults to the web Credential
+     * Management adapter; pass `null` to disable the feature entirely.
+     */
+    credentialAutofill?: CredentialAutofillAdapter | null;
+    /**
+     * Host end-user identity. Conversation memory is namespaced per identity
+     * (hashed LOCALLY, never sent by this module): logout/account switches swap
+     * to that identity's own conversation instead of leaking the previous one.
+     */
+    getUserId?: () => string | null;
     messages?: {
         catalogs?: Record<string, MessageCatalog>;
         overrides?: Partial<AgentMessages>;

package/dist/cjs/controller/AgentController.d.ts

@@ -74,6 +74,7 @@ export declare class AgentController {
     private readonly telemetry;
     private readonly consent;
     private readonly executor;
+    private readonly credentialAutofill;
     private readonly timings;
     private readonly chaining;
     private readonly ttsLocale;
@@ -89,7 +90,7 @@ export declare class AgentController {
     private consentModalVisible;
     private readonly sessionId;
     private sessionStarted;
-    private readonly conversation;
+    private conversation;
     private pending;
     private confirmationReasked;
     private confirmationVoiceActive;
@@ -116,6 +117,10 @@ export declare class AgentController {
     /** Persistence scope: internal orbs keep their memory under a separate key
      *  so a public orb sharing the same appId can never read it. */
     private conversationScope;
+    /** Current identity segment (LOCAL hash of the host's getUserId; never sent
+     *  anywhere). The conversation belongs to (app, scope, identity). */
+    private conversationIdentity;
+    private removeIdentityListeners;
     private loadingOlderExchanges;
     private loadOlderTimer;
     private readonly listeners;
@@ -123,6 +128,22 @@ export declare class AgentController {
     constructor(config: FiodosWebAgentConfig);
     private restorePersistedConversation;
     private persistConversation;
+    /**
+     * Re-evaluates the host identity and, when it changed, swaps conversations:
+     * the outgoing identity's session is saved under ITS private key (so a user
+     * who logs back in recovers it, honouring "never clear"), all in-memory
+     * state and UI are wiped, and the incoming identity's own session (usually
+     * empty) is restored. An anonymous visitor after a logout always starts
+     * clean — the previous user's transcript is never inherited.
+     */
+    private syncConversationIdentity;
+    /**
+     * Wipes the CURRENT identity's conversation: live memory, panel and the
+     * persisted blob. Hosts can call it from their logout for a hard wipe (by
+     * default a logout only parks the conversation under the user's private
+     * local key).
+     */
+    resetConversation(): void;
     getState(): AgentState;
     /** Update the REAL live activity and re-render (no-op when unchanged). */
     private setActivity;
@@ -171,6 +192,19 @@ export declare class AgentController {
     confirmPendingAction(): Promise<void>;
     cancelPendingAction(): void;
     private handleConfirmationTranscript;
+    /**
+     * Device capability flags advertised on each turn (never user data). Fresh
+     * per turn: cheap, and honest if the environment changes mid-session.
+     */
+    private platformCapabilities;
+    /**
+     * Live session verdict advertised on each turn (audience map — never user
+     * data): whether the user is signed in plus the app's boolean capability
+     * flags. Fresh per turn so login/logout mid-session is honest. Undefined
+     * when the host wired neither source (older installs — backend filters
+     * nothing, exactly today's behavior).
+     */
+    private sessionContext;
     private routeLabel;
     private actionLabel;
     /**

package/dist/cjs/controller/AgentController.js

@@ -19,6 +19,7 @@ exports.AgentController = void 0;
  *  - The agent only ever executes actions declared in the manifest.
  */
 const core_1 = require("@fiodos/core");
+const webCredentialAutofillAdapter_1 = require("../adapters/webCredentialAutofillAdapter");
 const errors_1 = require("../api/errors");
 const formatTurnError_1 = require("../api/formatTurnError");
 const backendClient_1 = require("../api/backendClient");
@@ -43,6 +44,7 @@ class AgentController {
         this.consentModalVisible = false;
         this.sessionId = randomSessionId();
         this.sessionStarted = false;
+        // Replaced wholesale on identity swaps / explicit resets.
         this.conversation = (0, core_1.createConversationSession)();
         this.pending = null;
         this.confirmationReasked = false;
@@ -72,6 +74,7 @@ class AgentController {
         /** Persistence scope: internal orbs keep their memory under a separate key
          *  so a public orb sharing the same appId can never read it. */
         this.conversationScope = 'public';
+        this.removeIdentityListeners = null;
         this.loadingOlderExchanges = false;
         this.loadOlderTimer = null;
         this.listeners = new Set();
@@ -92,12 +95,19 @@ class AgentController {
             appId: config.manifest.appId,
             version: config.consentVersion,
         });
+        // SMART SIGN-IN ships by default on web (browser password manager);
+        // hosts can override the adapter or pass null to opt out entirely.
+        this.credentialAutofill =
+            config.credentialAutofill === undefined
+                ? (0, webCredentialAutofillAdapter_1.createWebCredentialAutofillAdapter)()
+                : config.credentialAutofill;
         this.executor = (0, core_1.createActionExecutor)({
             manifest: config.manifest,
             registries: config.registries,
             navigation: config.navigation,
             messages: this.messages,
             isAuthenticated: config.isAuthenticated,
+            credentialAutofill: this.credentialAutofill,
         });
         this.timings = { ...types_1.DEFAULT_AGENT_TIMINGS, ...config.timings };
         // Chaining OFF by default; clamp to the same safe bounds as react/react-native.
@@ -131,15 +141,29 @@ class AgentController {
         });
         // Re-emit combined state whenever the speech machine advances.
         this.unsubscribeSpeech = this.speech.subscribe(() => this.emit());
+        this.conversationIdentity = (0, core_1.conversationIdentityKey)(config.getUserId?.());
         // Rehydrate the previous conversation (page reloads): the persisted blob
         // carries its own retention rule, so expiry is decided correctly even
         // before the published config arrives. Best-effort and non-blocking.
         void this.restorePersistedConversation();
+        // Logout/login usually happens on another screen: re-check identity when
+        // the tab regains focus or becomes visible again, besides before every turn.
+        if (typeof window !== 'undefined') {
+            const check = () => void this.syncConversationIdentity();
+            window.addEventListener('focus', check);
+            document.addEventListener('visibilitychange', check);
+            this.removeIdentityListeners = () => {
+                window.removeEventListener('focus', check);
+                document.removeEventListener('visibilitychange', check);
+            };
+        }
     }
     // ── Conversation persistence (survives page reloads) ───────────────────────
     async restorePersistedConversation() {
-        const restored = await (0, core_1.restoreConversationSession)(this.config.storage, this.config.manifest.appId, Date.now(), this.conversationScope);
-        if (!restored)
+        const identityAtStart = this.conversationIdentity;
+        const restored = await (0, core_1.restoreConversationSession)(this.config.storage, this.config.manifest.appId, Date.now(), this.conversationScope, identityAtStart);
+        // The identity may have changed again while the read resolved.
+        if (!restored || this.conversationIdentity !== identityAtStart)
             return;
         // Never clobber turns the user already made while the restore resolved.
         if (this.conversation.turns.length > 0 || this.conversation.uiArchive?.length)
@@ -151,7 +175,43 @@ class AgentController {
         this.emit();
     }
     persistConversation() {
-        void (0, core_1.persistConversationSession)(this.config.storage, this.config.manifest.appId, this.conversation, this.conversationRetentionMinutes, this.conversationScope);
+        void (0, core_1.persistConversationSession)(this.config.storage, this.config.manifest.appId, this.conversation, this.conversationRetentionMinutes, this.conversationScope, this.conversationIdentity);
+    }
+    /**
+     * Re-evaluates the host identity and, when it changed, swaps conversations:
+     * the outgoing identity's session is saved under ITS private key (so a user
+     * who logs back in recovers it, honouring "never clear"), all in-memory
+     * state and UI are wiped, and the incoming identity's own session (usually
+     * empty) is restored. An anonymous visitor after a logout always starts
+     * clean — the previous user's transcript is never inherited.
+     */
+    syncConversationIdentity() {
+        const next = (0, core_1.conversationIdentityKey)(this.config.getUserId?.());
+        if (next === this.conversationIdentity)
+            return false;
+        // 1. Park the outgoing identity's session under its own key.
+        this.persistConversation();
+        // 2. Wipe every trace from memory and the panel.
+        this.conversation = (0, core_1.createConversationSession)();
+        this.conversationIdentity = next;
+        this.lastExchange = null;
+        this.emit();
+        // 3. Bring in the new identity's own session, if any.
+        void this.restorePersistedConversation();
+        return true;
+    }
+    /**
+     * Wipes the CURRENT identity's conversation: live memory, panel and the
+     * persisted blob. Hosts can call it from their logout for a hard wipe (by
+     * default a logout only parks the conversation under the user's private
+     * local key).
+     */
+    resetConversation() {
+        this.cancelAll();
+        this.conversation = (0, core_1.createConversationSession)();
+        this.lastExchange = null;
+        void (0, core_1.clearPersistedConversation)(this.config.storage, this.config.manifest.appId, this.conversationScope, this.conversationIdentity);
+        this.emit();
     }
     // ── Subscription / state ───────────────────────────────────────────────────
     getState() {
@@ -532,6 +592,57 @@ class AgentController {
                 this.beginConfirmationVoiceWindow();
         }
     }
+    /**
+     * Device capability flags advertised on each turn (never user data). Fresh
+     * per turn: cheap, and honest if the environment changes mid-session.
+     */
+    platformCapabilities() {
+        let autofill = false;
+        try {
+            autofill = this.credentialAutofill?.isSupported() === true;
+        }
+        catch {
+            autofill = false;
+        }
+        return autofill ? { credentialAutofill: true } : undefined;
+    }
+    /**
+     * Live session verdict advertised on each turn (audience map — never user
+     * data): whether the user is signed in plus the app's boolean capability
+     * flags. Fresh per turn so login/logout mid-session is honest. Undefined
+     * when the host wired neither source (older installs — backend filters
+     * nothing, exactly today's behavior).
+     */
+    sessionContext() {
+        const { isAuthenticated, getSessionCapabilities } = this.config;
+        if (!isAuthenticated && !getSessionCapabilities)
+            return undefined;
+        let authenticated = null;
+        try {
+            const v = isAuthenticated?.();
+            authenticated = v == null ? null : Boolean(v);
+        }
+        catch {
+            authenticated = null;
+        }
+        let capabilities;
+        try {
+            const raw = getSessionCapabilities?.();
+            if (raw && typeof raw === 'object') {
+                const clean = {};
+                for (const [k, v] of Object.entries(raw)) {
+                    if (typeof v === 'boolean')
+                        clean[k] = v;
+                }
+                if (Object.keys(clean).length > 0)
+                    capabilities = clean;
+            }
+        }
+        catch {
+            capabilities = undefined;
+        }
+        return { authenticated, ...(capabilities ? { capabilities } : {}) };
+    }
     routeLabel(intent) {
         return this.config.manifest.routes.find((r) => r.intent === intent)?.label;
     }
@@ -717,6 +828,8 @@ class AgentController {
                         isContinuation: true,
                         chainStep: step,
                         lastStep,
+                        platformCapabilities: this.platformCapabilities(),
+                        sessionContext: this.sessionContext(),
                         ...(0, backendClient_1.buildManifestPayload)(this.config.manifest),
                     }, { signal: controller.signal });
                     oc = await this.applyOutcome(turn, routeNow, snap?.context ?? {}, state.userMessage);
@@ -820,6 +933,9 @@ class AgentController {
                 this.setPhase('idle');
             return;
         }
+        // Identity gate: if the host user changed since the last turn (login,
+        // logout, account switch), swap conversations BEFORE recording anything.
+        this.syncConversationIdentity();
         this.setPhase('thinking');
         // REAL activity: the request is genuinely in flight from this moment.
         this.setActivity({ kind: 'thinking' });
@@ -871,6 +987,8 @@ class AgentController {
                 conversationHistory: conv.history,
                 conversationSummary: conv.summary ?? undefined,
                 sessionId: this.sessionId,
+                platformCapabilities: this.platformCapabilities(),
+                sessionContext: this.sessionContext(),
                 ...(0, backendClient_1.buildManifestPayload)(this.config.manifest),
             }, { signal: controller.signal });
             outcome = await this.applyOutcome(turn, currentRoute, snapshot?.context ?? {}, text);
@@ -1112,6 +1230,8 @@ class AgentController {
     }
     dispose() {
         this.cancelAll();
+        this.removeIdentityListeners?.();
+        this.removeIdentityListeners = null;
         if (this.loadOlderTimer) {
             clearTimeout(this.loadOlderTimer);
             this.loadOlderTimer = null;

package/dist/cjs/dropin/createFiodosAgent.d.ts

@@ -13,6 +13,7 @@
  */
 import { type ActionRegistries, type AppManifest } from '@fiodos/core';
 import { AgentController } from '../controller/AgentController';
+import type { AgentScreenSnapshot } from '../context/screenContextStore';
 import { type MountOrbOptions, type MountedOrb } from '../orb/mountOrb';
 import type { FiodosWebAgentConfig } from '../config/types';
 export interface CreateFiodosAgentOptions {
@@ -37,8 +38,22 @@ export interface CreateFiodosAgentOptions {
     sttLocale?: string;
     /** Host router navigate delegate. Defaults to location.assign. */
     navigate?: (route: string) => void;
+    /**
+     * Current route/screen resolver for the agent's screen awareness. Defaults
+     * to location.pathname + search. Apps whose screens are CLIENT STATE (no URL
+     * change) pass the generated `fyodosGetCurrentRoute` here so the orb knows
+     * which screen the user is on (see screen-truth wiring).
+     */
+    getCurrentRoute?: () => string | null;
     /** Host auth check for actions requiring auth. */
-    isAuthenticated?: () => boolean;
+    isAuthenticated?: () => boolean | null | undefined;
+    /**
+     * Fine-grained session capability flags (audience map, e.g.
+     * { has_payment_method: true }) from the generated session wiring. Boolean
+     * flags only; sent with each turn so the orb shows this user only THEIR
+     * available actions.
+     */
+    getSessionCapabilities?: () => Record<string, boolean> | null | undefined;
     /** Voice id forwarded to the backend TTS. */
     ttsVoice?: string | (() => string | undefined);
     /** End-user id for rate limiting / telemetry correlation. */
@@ -59,6 +74,22 @@ export interface FiodosAgentHandle {
     orb: MountedOrb | null;
     /** Resolves once the controller is ready (immediately on the manual path). */
     ready: Promise<AgentController | null>;
+    /**
+     * Wipes the current identity's conversation (live memory + persisted blob).
+     * Call it from the app's logout for a hard wipe; no-op until ready.
+     */
+    resetConversation(): void;
+    /**
+     * Publishes WHAT THE USER IS SEEING so 'execute' actions can target it —
+     * the embed-host equivalent of the React `useAgentScreenContext` hook.
+     * Hosts without our SDK on screens (Dynamics web resources, WinCC CWCs)
+     * call this whenever their form/record/view changes. On the auto-fetch
+     * path, calls made before the controller is ready are kept and applied on
+     * ready, so hosts don't need to await `ready` themselves.
+     */
+    setScreenContext(snapshot: AgentScreenSnapshot): void;
+    /** Clears a previously published snapshot (e.g. the record was closed). */
+    clearScreenContext(): void;
     destroy(): void;
 }
 export declare function createFiodosAgent(options: CreateFiodosAgentOptions): FiodosAgentHandle;

package/dist/cjs/dropin/createFiodosAgent.js

@@ -68,13 +68,18 @@ function assemble(options, manifest, baseUrl) {
         manifest,
         locale,
         sttLocale,
-        navigation: (0, webNavigationAdapter_1.createWebNavigationAdapter)({ navigate: options.navigate ?? defaultNavigate }),
+        navigation: (0, webNavigationAdapter_1.createWebNavigationAdapter)({
+            navigate: options.navigate ?? defaultNavigate,
+            getCurrentRoute: options.getCurrentRoute,
+        }),
         registries: options.registries ?? { handlers: {}, idempotencyCheckers: {} },
         backend,
         voice: (0, webVoiceAdapter_1.createWebVoiceAdapter)(),
         storage: (0, webStorageAdapter_1.createWebStorageAdapter)(),
         telemetry,
         isAuthenticated: options.isAuthenticated,
+        getSessionCapabilities: options.getSessionCapabilities,
+        getUserId: options.getUserId,
         ttsVoice: options.ttsVoice,
         ...options.configOverrides,
     };
@@ -85,6 +90,9 @@ function assemble(options, manifest, baseUrl) {
 function createFiodosAgent(options) {
     const baseUrl = (options.baseUrl ?? clientBootstrap_1.DEFAULT_WEB_API_URL).replace(/\/$/, '');
     const shouldMount = options.mount !== false;
+    // One stable owner id per handle: the host is "one screen" from the store's
+    // point of view, so consecutive setScreenContext calls replace each other.
+    const contextOwner = Symbol('fiodos-embed-host');
     // ── Manual path: manifest provided → fully synchronous (back-compat). ───────
     if (options.manifest) {
         const controller = assemble(options, options.manifest, baseUrl);
@@ -97,6 +105,15 @@ function createFiodosAgent(options) {
             controller,
             orb,
             ready: Promise.resolve(controller),
+            resetConversation() {
+                controller.resetConversation();
+            },
+            setScreenContext(snapshot) {
+                controller.screenStore.set(contextOwner, snapshot);
+            },
+            clearScreenContext() {
+                controller.screenStore.clear(contextOwner);
+            },
             destroy() {
                 orb?.unmount();
                 controller.dispose();
@@ -105,10 +122,28 @@ function createFiodosAgent(options) {
         return handle;
     }
     // ── Auto path (React parity): fetch manifest by apiKey, then assemble. ──────
+    // Context published before the controller resolves is buffered (last one
+    // wins) and applied on ready — hosts fire form events without awaiting us.
+    let pendingSnapshot;
     const handle = {
         controller: null,
         orb: null,
         ready: Promise.resolve(null),
+        resetConversation() {
+            handle.controller?.resetConversation();
+        },
+        setScreenContext(snapshot) {
+            if (handle.controller)
+                handle.controller.screenStore.set(contextOwner, snapshot);
+            else
+                pendingSnapshot = snapshot;
+        },
+        clearScreenContext() {
+            if (handle.controller)
+                handle.controller.screenStore.clear(contextOwner);
+            else
+                pendingSnapshot = null;
+        },
         destroy() {
             cancelled = true;
             handle.orb?.unmount();
@@ -144,6 +179,9 @@ function createFiodosAgent(options) {
                 return null;
             }
             handle.controller = controller;
+            if (pendingSnapshot)
+                controller.screenStore.set(contextOwner, pendingSnapshot);
+            pendingSnapshot = undefined;
             handle.orb = shouldMount ? (0, mountOrb_1.mountOrb)(controller, options.orb) : null;
             if (shouldMount && options.apiKey) {
                 void (0, clientBootstrap_1.sendOrbSeen)({ baseUrl, apiKey: options.apiKey });

package/dist/cjs/embed/dynamics.d.ts

@@ -0,0 +1,61 @@
+import type { AgentScreenSnapshot } from '../context/screenContextStore';
+interface XrmAttributeLike {
+    getName(): string;
+    getValue(): unknown;
+    /** Present on optionset/lookup attributes; preferred over raw values. */
+    getText?(): string | string[] | null;
+}
+interface XrmEntityLike {
+    getEntityName(): string;
+    /** Record GUID, usually brace-wrapped: "{1D2C...}". Empty on create forms. */
+    getId(): string;
+    getPrimaryAttributeValue?(): string | null;
+    attributes?: {
+        forEach(cb: (attribute: XrmAttributeLike) => void): void;
+    };
+    /** Model-driven apps expose save events here (Xrm ≥ 9.x). */
+    addOnPostSave?(handler: () => void): void;
+    removeOnPostSave?(handler: () => void): void;
+}
+export interface DynamicsFormContextLike {
+    data: {
+        entity: XrmEntityLike;
+    };
+    ui?: {
+        getFormType?(): number;
+    };
+}
+/** The subset of FiodosAgentHandle the bridge needs (keeps this module cheap to test). */
+export interface ScreenContextSink {
+    setScreenContext(snapshot: AgentScreenSnapshot): void;
+    clearScreenContext(): void;
+}
+export interface DynamicsSnapshotOptions {
+    /**
+     * Logical names of the attributes to expose to the agent. When omitted, the
+     * first `maxAttributes` non-empty scalar attributes are included.
+     */
+    attributes?: string[];
+    /** Cap when no allowlist is given. Default 12. */
+    maxAttributes?: number;
+}
+/** "{1D2C…}" → "1d2c…" (Web API URLs want bare lowercase GUIDs). */
+export declare function normalizeDynamicsId(rawId: string): string;
+/**
+ * Builds the AgentScreenSnapshot for the current form state, or null when
+ * there is nothing referenceable yet (create form: no record id).
+ */
+export declare function dynamicsFormSnapshot(formContext: DynamicsFormContextLike, options?: DynamicsSnapshotOptions): AgentScreenSnapshot | null;
+export interface DynamicsContextBridge {
+    /** Re-reads the form and republishes the snapshot (wire to OnChange/OnSave). */
+    refresh(): void;
+    /** Stops publishing and clears the agent's screen context. */
+    disconnect(): void;
+}
+/**
+ * Publishes the form snapshot now, republishes after every save (when the
+ * form exposes OnPostSave), and clears the context on disconnect. Call it from
+ * the form's OnLoad handler.
+ */
+export declare function connectDynamicsFormContext(agent: ScreenContextSink, formContext: DynamicsFormContextLike, options?: DynamicsSnapshotOptions): DynamicsContextBridge;
+export {};