@gengage/assistant-fe 0.6.26 → 0.6.28

package/dist/agentic/types.d.ts

@@ -2,6 +2,7 @@ import type { ProcessActionRequest } from '../common/transport.js';
 import type { StreamEvent, UISpec } from '../common/types.js';
 import type { NormalizedProduct } from './events/product-normalize.js';
 import type { ProductSimilarityProfile } from './algos/similarity.js';
+import type { ToolArgSchema } from './worker/tool-schema.js';
 export interface ChatThread {
     id: string;
     started_at: string;
@@ -9,8 +10,10 @@ export interface ChatThread {
 }
 export type ChatPanel = Record<string, unknown>;
 export interface ChatMessage {
-    role: 'user' | 'assistant';
+    role: 'user' | 'assistant' | 'tool_result';
     content: string;
+    name?: string;
+    details?: unknown;
 }
 export interface ChatMeta {
     locale: string;
@@ -46,6 +49,9 @@ export interface FlowStepCtx {
     accountConfig: Record<string, unknown>;
     catalogMapper?: CatalogMapper | undefined;
     similarityMapper?: SimilarityMapper | undefined;
+    beClient?: BeClient;
+    toolBridge?: ToolBridge;
+    signal?: AbortSignal;
 }
 export type FlowValue<T> = T | ((ctx: FlowStepCtx) => Awaitable<T>);
 export type FlowPatch = (ctx: ChatContext, result: unknown, snapshot: FlowStepCtx) => Awaitable<Partial<ChatContext> | null | undefined>;
@@ -86,6 +92,7 @@ export interface ToolStep {
     kind: 'tool';
     name: string;
     input: FlowValue<unknown>;
+    parameters?: ToolArgSchema;
     timeoutMs?: FlowValue<number | undefined>;
     confirm?: FlowConfirmationGate;
     out?: string;
@@ -147,7 +154,30 @@ export type ToolFn = (input: unknown) => unknown | Promise<unknown>;
 export type ToolMap = Record<string, ToolFn>;
 export type CatalogMapper = (raw: Record<string, unknown>) => NormalizedProduct | null;
 export type SimilarityMapper = (raw: Record<string, unknown>) => ProductSimilarityProfile | null;
-export interface AccountModule {
+export interface BeforeToolCallResult {
+    block?: boolean;
+    reason?: string;
+    args?: unknown;
+}
+export interface AfterToolCallResult {
+    result?: unknown;
+    terminate?: boolean;
+}
+export interface BeforeBeOpResult {
+    input?: unknown;
+    cached?: unknown;
+}
+export interface AfterBeOpResult {
+    result?: unknown;
+}
+export interface AgentHooks {
+    beforeToolCall?(name: string, args: unknown, ctx: FlowStepCtx): Awaitable<BeforeToolCallResult | void | undefined>;
+    afterToolCall?(name: string, result: unknown, ctx: FlowStepCtx): Awaitable<AfterToolCallResult | void | undefined>;
+    transformContext?(ctx: ChatContext): Awaitable<ChatContext | void | undefined>;
+    beforeBeOp?(op: string, input: unknown, ctx: FlowStepCtx): Awaitable<BeforeBeOpResult | void | undefined>;
+    afterBeOp?(op: string, result: unknown, ctx: FlowStepCtx): Awaitable<AfterBeOpResult | void | undefined>;
+}
+export interface AccountModule<TAccountConfig extends Record<string, unknown> = Record<string, unknown>> {
     accountId?: string;
     defaultLocale?: string;
     flows: Record<string, Flow>;
@@ -155,8 +185,9 @@ export interface AccountModule {
     adapters?: FlowAdapterMap;
     catalogMapper?: CatalogMapper;
     similarityMapper?: SimilarityMapper;
-    accountConfig?: Record<string, unknown>;
+    accountConfig?: TAccountConfig;
     trace?: AgentTraceCallback;
+    hooks?: AgentHooks;
     contextPersistence?: {
         panelKeys?: readonly string[];
         panelKeyLimits?: Record<string, number>;

package/dist/agentic/worker/agent-ui-steps.d.ts

@@ -0,0 +1,43 @@
+import type { ChatContext, FlowStep, UiSpecEnvelope } from '../types.js';
+import type { StreamEvent } from '../../common/types.js';
+import { type RoundObservation, type SearchFollowUpPill } from './agent-ui.js';
+export interface ToolObservationEnvelope extends RoundObservation {
+    name?: string;
+    arguments?: Record<string, unknown>;
+    observation?: {
+        status?: string;
+        products?: unknown[];
+        query?: unknown;
+        source?: unknown;
+        count?: unknown;
+        comparison_table?: unknown;
+        key_differences?: unknown;
+        recommendation?: {
+            sku?: unknown;
+            reason?: unknown;
+        };
+        surface?: {
+            product?: unknown;
+        };
+        [key: string]: unknown;
+    };
+}
+export interface ToolUiStepsDeps {
+    obsKey?: string;
+    uiSpec: (envelope: UiSpecEnvelope) => StreamEvent;
+    productsUiSpec: (products: unknown[]) => UiSpecEnvelope;
+    actionButtonsUiSpec: (pills: SearchFollowUpPill[]) => UiSpecEnvelope;
+    comparisonUiSpec: (input: {
+        products: unknown[];
+        comparison_table?: unknown;
+        key_differences?: unknown;
+        recommended_choice_sku?: unknown;
+        recommended_choice?: unknown;
+    }) => UiSpecEnvelope;
+    productDetailsUiSpec: (product: unknown) => UiSpecEnvelope;
+    similarsFollowupSteps?: () => readonly FlowStep[];
+    pdpFollowupProduct?: (bag: Record<string, unknown>, context: ChatContext) => unknown;
+    gridLimit?: number;
+}
+export declare function buildToolUiSteps(deps: ToolUiStepsDeps): FlowStep[];
+export declare function buildPdpFollowupSteps(deps: ToolUiStepsDeps): FlowStep[];

package/dist/agentic/worker/agent-ui.d.ts

@@ -0,0 +1,44 @@
+interface UiSpecLike {
+    spec?: {
+        root?: string;
+        elements?: Record<string, {
+            type?: string;
+            props?: Record<string, unknown>;
+        } | undefined>;
+    };
+    [key: string]: unknown;
+}
+export interface SearchFollowUpProduct {
+    sku?: unknown;
+    url?: unknown;
+    [key: string]: unknown;
+}
+export interface SearchFollowUpContext {
+    meta?: {
+        locale?: unknown;
+    };
+}
+export interface SearchFollowUpAccountConfig {
+    locale?: unknown;
+    defaultLocale?: unknown;
+}
+export interface SearchFollowUpPill {
+    label: string;
+    action: {
+        type: string;
+        payload: Record<string, unknown>;
+    };
+}
+export declare function searchFollowUpPills(products: readonly SearchFollowUpProduct[] | null | undefined, options?: {
+    context?: SearchFollowUpContext;
+    accountConfig?: SearchFollowUpAccountConfig;
+}): SearchFollowUpPill[];
+export interface RoundObservation {
+    observation?: {
+        products?: readonly unknown[];
+    };
+    [key: string]: unknown;
+}
+export declare function mergeRoundProducts(observations: readonly (RoundObservation | null | undefined)[] | null | undefined, limit?: number): Record<string, unknown>[];
+export declare function withSimilarsAppend<T extends UiSpecLike>(envelope: T): T;
+export {};

package/dist/agentic/worker/be-client.d.ts

@@ -1,6 +1,18 @@
 import { type JwtProvider } from './jwt-mint.js';
-import type { BrowserCachePolicy } from '../types.js';
-interface InvokeBeOpArgs {
+import type { Awaitable, BrowserCachePolicy } from '../types.js';
+export interface BeClientInterceptors {
+    beforeRequest?(args: InvokeBeOpArgs, request: {
+        url: string;
+        init: RequestInit;
+    }): Awaitable<{
+        init?: RequestInit;
+        cached?: Record<string, unknown>;
+    } | void | undefined>;
+    afterResponse?(args: InvokeBeOpArgs, result: Record<string, unknown>): Awaitable<{
+        result?: Record<string, unknown>;
+    } | void | undefined>;
+}
+export interface InvokeBeOpArgs {
     beUrl: string;
     accountId: string;
     devJwtSecret?: string | undefined;
@@ -14,6 +26,6 @@ interface InvokeBeOpArgs {
     cacheKey?: string | undefined;
     browserCache?: BrowserCachePolicy | undefined;
     signal?: AbortSignal | undefined;
+    interceptors?: BeClientInterceptors | undefined;
 }
-export declare function invokeBeOp({ beUrl, accountId, devJwtSecret, tokenBrokerUrl, tokenBrokerAudience, jwtProvider, parentUrl, op, input, cacheTtlS, cacheKey, browserCache, signal, }: InvokeBeOpArgs): Promise<Record<string, unknown>>;
-export {};
+export declare function invokeBeOp(args: InvokeBeOpArgs): Promise<Record<string, unknown>>;

package/dist/agentic/worker/coalesce.d.ts

@@ -0,0 +1,25 @@
+export interface SingleFlightOptions {
+    ttlMs?: number;
+    clock?: () => number;
+}
+export type SingleFlightExecutor<TInput, TResult> = (input: TInput) => Promise<TResult>;
+export type SingleFlightKeyFn<TInput> = (input: TInput) => string | null | undefined;
+export declare function singleFlight<TInput, TResult>(executor: SingleFlightExecutor<TInput, TResult>, keyFn: SingleFlightKeyFn<TInput>, options?: SingleFlightOptions): SingleFlightExecutor<TInput, TResult>;
+interface CartInput {
+    cartCode?: unknown;
+    sku?: unknown;
+    productCode?: unknown;
+    quantity?: unknown;
+    qty?: unknown;
+    variantId?: unknown;
+    variantCode?: unknown;
+    product?: {
+        sku?: unknown;
+        cart_code?: unknown;
+        variantId?: unknown;
+    };
+}
+type CartImpl<TResult> = (input: CartInput) => Promise<TResult>;
+export declare function coalesceAddToCart<TResult>(impl: CartImpl<TResult>): (input?: CartInput) => Promise<TResult>;
+export declare function __resetAllCartCoalescersForTesting(): void;
+export {};

package/dist/agentic/worker/compaction.d.ts

@@ -0,0 +1,12 @@
+import type { ChatContext, ChatMessage } from '../types.js';
+export interface CompactionOptions {
+    threshold?: number;
+    retainTail?: number;
+}
+export interface CompactionRequest {
+    messagesToSummarize: readonly ChatMessage[];
+    retainedTail: readonly ChatMessage[];
+}
+export declare function shouldCompact(messages: readonly ChatMessage[] | null | undefined, options?: CompactionOptions): boolean;
+export declare function buildCompactionRequest(messages: readonly ChatMessage[], options?: CompactionOptions): CompactionRequest | null;
+export declare function applyCompactionResult(context: ChatContext, summary: string, options?: CompactionOptions): ChatContext;

package/dist/agentic/worker/pdp-hydrate.d.ts

@@ -0,0 +1,30 @@
+type ResolveProductsResult<TProduct> = {
+    products?: TProduct[];
+} & Record<string, unknown>;
+type ResolveProductsInput = {
+    hydrateFromPdp?: boolean;
+    [key: string]: unknown;
+};
+export interface PdpHydrationOptions<TProduct extends {
+    sku?: unknown;
+    url?: unknown;
+}> {
+    accountId: string;
+    allowedHostnames: readonly string[];
+    productFromPage: (doc: Document, url: string) => TProduct | null;
+    mergeProduct?: (base: TProduct, parsed: TProduct) => TProduct;
+    needsHydration?: (product: TProduct) => boolean;
+    fetchOptions?: RequestInit;
+    maxConcurrency?: number;
+}
+export interface WrappedResolveProducts<TProduct, TResult extends ResolveProductsResult<TProduct>> {
+    (input?: ResolveProductsInput): Promise<TResult>;
+    __resetCacheForTesting(): void;
+    __cacheSizeForTesting(): number;
+}
+export declare function wrapResolveProductsWithPdpHydration<TProduct extends {
+    sku?: unknown;
+    url?: unknown;
+}, TResult extends ResolveProductsResult<TProduct>>(baseResolveProducts: (input: ResolveProductsInput) => Promise<TResult>, options: PdpHydrationOptions<TProduct>): WrappedResolveProducts<TProduct, TResult>;
+export declare function __resetAllPdpHydratorsForTesting(): void;
+export {};

package/dist/agentic/worker/tool-schema.d.ts

@@ -0,0 +1,19 @@
+export interface ToolArgSchema {
+    type?: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    required?: readonly string[];
+    properties?: Readonly<Record<string, ToolArgSchema>>;
+    items?: ToolArgSchema;
+    enum?: readonly unknown[];
+    minItems?: number;
+    maxItems?: number;
+    minLength?: number;
+    minimum?: number;
+    maximum?: number;
+}
+export type ToolArgValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function validateToolArgs(schema: ToolArgSchema | undefined, args: unknown): ToolArgValidationResult;

package/dist/agentic/worker.d.ts

@@ -34,5 +34,19 @@ export { createPrivacyHelpers, plainMessageContent } from './util/common/privacy
 export { compactProductSurfaceForLlm, mergeProductSurfaceEvidence, productSurfaceReviewText, } from './util/common/product-surface.js';
 export { anonymousRequestText as retailAnonymousRequestText, anonymizeMessages as retailAnonymizeMessages, redactPii as retailRedactPii, } from './util/common/retail-privacy.js';
 export { firstArrayValue, routeFlowParams, routeSkuList } from './util/common/route-params.js';
-export type { AccountModule, AgentLoopPatch, AgentLoopPredicate, AgentLoopStep, AgentConfirmationRequest, AgentConfirmationResult, AgentMemoryProvider, AgentTraceCallback, AgentTraceEvent, AdapterStep, AgentBeaconPayload, Awaitable, BeClient, BeOpStep, BranchStep, BrowserCachePolicy, ChatContext, CommitStep, EmitStep, Flow, FlowAdapterFn, FlowAdapterMap, FlowConfirmationGate, FlowConfirmationRequest, FlowConfirmationValue, FlowPatch, FlowStep, FlowStepCtx, FlowValue, MemoryTier, ParallelStep, RefusalStep, ToolFn, ToolMap, ToolStep, } from './types.js';
+export type { AccountModule, AfterBeOpResult, AfterToolCallResult, AgentHooks, AgentLoopPatch, AgentLoopPredicate, AgentLoopStep, AgentConfirmationRequest, AgentConfirmationResult, AgentMemoryProvider, AgentTraceCallback, AgentTraceEvent, AdapterStep, AgentBeaconPayload, BeforeBeOpResult, BeforeToolCallResult, Awaitable, BeClient, BeOpStep, BranchStep, BrowserCachePolicy, ChatContext, CommitStep, EmitStep, Flow, FlowAdapterFn, FlowAdapterMap, FlowConfirmationGate, FlowConfirmationRequest, FlowConfirmationValue, FlowPatch, FlowStep, FlowStepCtx, FlowValue, MemoryTier, ParallelStep, RefusalStep, ToolFn, ToolMap, ToolStep, } from './types.js';
 export type { BeOpInputBase, CompareInput, CompareOutput, GssInstallmentOption, GssProductDetails, GssProductFeature, GssProductQuestionAnswer, GssProductReview, GssProductSeller, GssShippingOption, IntentOpInput, IntentOpOutput, LocaleCode, MoneyValue, ProductAnswerInput, ProductAnswerOutput, RefPayload, UiSpec, UiSpecElement, UiSpecElementType, UiSpecEvent, } from './contracts/agentic-contracts.js';
+export { validateToolArgs } from './worker/tool-schema.js';
+export type { ToolArgSchema, ToolArgValidationResult } from './worker/tool-schema.js';
+export { __resetAllCartCoalescersForTesting, coalesceAddToCart, singleFlight } from './worker/coalesce.js';
+export type { SingleFlightExecutor, SingleFlightKeyFn, SingleFlightOptions } from './worker/coalesce.js';
+export { __resetAllPdpHydratorsForTesting, wrapResolveProductsWithPdpHydration } from './worker/pdp-hydrate.js';
+export type { PdpHydrationOptions, WrappedResolveProducts } from './worker/pdp-hydrate.js';
+export type { BeClientInterceptors, InvokeBeOpArgs } from './worker/be-client.js';
+export type { PendingMessage, PendingMessageKind, QueueMode, SavePointEntry } from './context/context-store.js';
+export { mergeRoundProducts, searchFollowUpPills, withSimilarsAppend } from './worker/agent-ui.js';
+export type { RoundObservation, SearchFollowUpAccountConfig, SearchFollowUpContext, SearchFollowUpPill, SearchFollowUpProduct, } from './worker/agent-ui.js';
+export { applyCompactionResult, buildCompactionRequest, shouldCompact } from './worker/compaction.js';
+export type { CompactionOptions, CompactionRequest } from './worker/compaction.js';
+export { buildPdpFollowupSteps, buildToolUiSteps } from './worker/agent-ui-steps.js';
+export type { ToolObservationEnvelope, ToolUiStepsDeps } from './worker/agent-ui-steps.js';