@kuralle-agents/engagement 0.3.0

package/dist/render-instagram-interactive.js

@@ -0,0 +1,78 @@
+/** Instagram button-template title limit (R-11 / Meta quick-reply parity). */
+export const IG_TITLE_MAX = 20;
+/** Instagram button template — max buttons per message. */
+export const IG_BUTTON_COUNT_MAX = 3;
+/** Instagram generic-template carousel — max elements. */
+export const IG_CAROUSEL_COUNT_MAX = 10;
+function assertIgTitle(label, optionId) {
+    if (label.length > IG_TITLE_MAX) {
+        throw new Error(`interactive: title for "${optionId}" exceeds ${IG_TITLE_MAX} characters (got ${label.length})`);
+    }
+}
+/**
+ * Renders author choices to a channel-neutral `InteractiveMessage` for Instagram:
+ * ≤3 → button template; 4–10 → generic-template carousel via list shape.
+ * Quick-replies (≤13) are a future enhancement — not used in this cut.
+ */
+export function renderInstagramInteractive(options, prompt) {
+    if (options.length === 0) {
+        throw new Error('interactive: at least one option is required');
+    }
+    if (options.some((o) => o.flow)) {
+        throw new Error('interactive: flow messages are not supported on Instagram');
+    }
+    if (options.length > IG_CAROUSEL_COUNT_MAX) {
+        throw new Error(`interactive: too many options (max ${IG_CAROUSEL_COUNT_MAX} carousel elements)`);
+    }
+    if (options.some((o) => o.url)) {
+        const urlOptions = options.filter((o) => o.url);
+        if (urlOptions.length > IG_BUTTON_COUNT_MAX) {
+            throw new Error(`interactive: too many URL options (max ${IG_BUTTON_COUNT_MAX} buttons)`);
+        }
+        for (const o of urlOptions) {
+            assertIgTitle(o.label, o.id);
+        }
+        return {
+            type: 'buttons',
+            body: prompt,
+            action: {
+                type: 'buttons',
+                buttons: urlOptions.map((o) => ({ id: o.id, title: o.label })),
+            },
+        };
+    }
+    if (options.length <= IG_BUTTON_COUNT_MAX) {
+        for (const o of options) {
+            assertIgTitle(o.label, o.id);
+        }
+        return {
+            type: 'buttons',
+            body: prompt,
+            action: {
+                type: 'buttons',
+                buttons: options.map((o) => ({ id: o.id, title: o.label })),
+            },
+        };
+    }
+    for (const o of options) {
+        assertIgTitle(o.label, o.id);
+    }
+    return {
+        type: 'list',
+        body: prompt,
+        action: {
+            type: 'list',
+            button: 'Choose',
+            sections: [
+                {
+                    title: 'Options',
+                    rows: options.map((o) => ({
+                        id: o.id,
+                        title: o.label,
+                        description: o.description,
+                    })),
+                },
+            ],
+        },
+    };
+}

package/dist/resolve-inbound-instagram.d.ts

@@ -0,0 +1,6 @@
+import type { InboundMessage } from '@kuralle-agents/messaging';
+import type { ResolvedSelection } from '@kuralle-agents/core';
+export declare function resolveInboundInstagram(m: InboundMessage): {
+    input: string;
+    selection?: ResolvedSelection;
+};

package/dist/resolve-inbound-instagram.js

@@ -0,0 +1,10 @@
+export function resolveInboundInstagram(m) {
+    const interactiveId = m.interactive?.id;
+    if (interactiveId) {
+        return { input: interactiveId, selection: { id: interactiveId } };
+    }
+    if (m.button?.payload) {
+        return { input: m.button.payload, selection: { id: m.button.payload } };
+    }
+    return { input: m.text ?? '', selection: undefined };
+}

package/dist/resolve-inbound-whatsapp.d.ts

@@ -0,0 +1,7 @@
+import type { InboundMessage } from '@kuralle-agents/messaging';
+import type { ResolvedSelection } from '@kuralle-agents/core';
+/** S3 interactive-then-text resolution (sync; mirrors InteractiveResolver + TextResolver). */
+export declare function resolveInboundWhatsApp(m: InboundMessage): {
+    input: string;
+    selection?: ResolvedSelection;
+};

package/dist/resolve-inbound-whatsapp.js

@@ -0,0 +1,17 @@
+/** S3 interactive-then-text resolution (sync; mirrors InteractiveResolver + TextResolver). */
+export function resolveInboundWhatsApp(m) {
+    const interactiveId = m.interactive?.id;
+    if (interactiveId) {
+        return { input: interactiveId, selection: { id: interactiveId } };
+    }
+    if (m.button?.payload) {
+        return { input: m.button.payload, selection: { id: m.button.payload } };
+    }
+    if (m.interactive?.formResponse) {
+        return {
+            input: '__flow__',
+            selection: { formData: m.interactive.formResponse },
+        };
+    }
+    return { input: m.text ?? '', selection: undefined };
+}

package/dist/scheduler.d.ts

@@ -0,0 +1,27 @@
+/** A unit of deferred work (broadcast step / drip step). Shape is engagement-internal. */
+export interface SendJob {
+    kind: string;
+    payload: Record<string, unknown>;
+}
+export interface Scheduler {
+    enqueue(job: SendJob, opts?: {
+        delayMs?: number;
+    }): Promise<string>;
+    cancel(jobId: string): Promise<void>;
+}
+export type InjectableTimer = {
+    set(fn: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+};
+/**
+ * Default in-process scheduler (timer-based). For single-process/dev.
+ * Production adapters (interface-compatible, not implemented here):
+ *   - BullMQ (Redis-backed queue)
+ *   - Google Cloud Tasks
+ *   - cron / system scheduler
+ * Inject a durable adapter for multi-process / serverless.
+ */
+export declare function createInProcessScheduler(opts: {
+    run: (job: SendJob) => void | Promise<void>;
+    timer?: InjectableTimer;
+}): Scheduler;

package/dist/scheduler.js

@@ -0,0 +1,36 @@
+const defaultTimer = {
+    set: (fn, ms) => setTimeout(fn, ms),
+    clear: (handle) => clearTimeout(handle),
+};
+/**
+ * Default in-process scheduler (timer-based). For single-process/dev.
+ * Production adapters (interface-compatible, not implemented here):
+ *   - BullMQ (Redis-backed queue)
+ *   - Google Cloud Tasks
+ *   - cron / system scheduler
+ * Inject a durable adapter for multi-process / serverless.
+ */
+export function createInProcessScheduler(opts) {
+    const timer = opts.timer ?? defaultTimer;
+    let nextJobId = 0;
+    const handles = new Map();
+    return {
+        async enqueue(job, options) {
+            const jobId = String(++nextJobId);
+            const delayMs = options?.delayMs ?? 0;
+            const handle = timer.set(() => {
+                handles.delete(jobId);
+                void opts.run(job);
+            }, delayMs);
+            handles.set(jobId, handle);
+            return jobId;
+        },
+        async cancel(jobId) {
+            const handle = handles.get(jobId);
+            if (handle === undefined)
+                return;
+            timer.clear(handle);
+            handles.delete(jobId);
+        },
+    };
+}

package/dist/selector.d.ts

@@ -0,0 +1,3 @@
+import { type LanguageModel } from 'ai';
+import type { TemplateSelector } from './strategist.js';
+export declare function aiTemplateSelector(model: LanguageModel): TemplateSelector;

package/dist/selector.js

@@ -0,0 +1,45 @@
+import { generateObject } from 'ai';
+import { z } from 'zod';
+const selectionSchema = z.object({
+    fit: z.boolean(),
+    name: z.string().nullable(),
+    language: z.string().nullable(),
+    params: z.record(z.string(), z.string()).nullable(),
+});
+export function aiTemplateSelector(model) {
+    return {
+        async select({ text, intent, candidates, flowState }) {
+            if (candidates.length === 0)
+                return null;
+            const candidateLines = candidates
+                .map((c) => `- ${c.name} (${c.language}, ${c.category}): params=[${c.params
+                .map((p) => `${p.key}${p.required ? '*' : ''}`)
+                .join(', ')}]`)
+                .join('\n');
+            const flowHint = flowState && Object.keys(flowState).length > 0
+                ? `Flow state:\n${JSON.stringify(flowState)}\n\n`
+                : '';
+            const { object } = await generateObject({
+                model,
+                schema: selectionSchema,
+                system: 'You choose the best WhatsApp message template for a user message. ' +
+                    'Only pick from the listed candidates. Output schema fields only.',
+                prompt: `User message:\n${text}\n` +
+                    (intent ? `Intent: ${intent}\n` : '') +
+                    flowHint +
+                    `Candidates:\n${candidateLines}\n\n` +
+                    'Return fit:true with name, language, and params when a candidate matches; otherwise fit:false.',
+            });
+            if (!object.fit || object.name == null)
+                return null;
+            const matched = candidates.find((c) => c.name === object.name);
+            if (!matched)
+                return null;
+            return {
+                name: object.name,
+                language: object.language ?? matched.language,
+                params: object.params ?? {},
+            };
+        },
+    };
+}

package/dist/simulator.d.ts

@@ -0,0 +1,44 @@
+import type { Runtime } from '@kuralle-agents/core';
+import { createMessagingRouter } from '@kuralle-agents/messaging';
+import type { PlatformClient, WindowStore } from '@kuralle-agents/messaging';
+import type { EngagementBridge } from './engagement.js';
+export interface SimChannel {
+    platform: string;
+}
+export type SimSendKind = 'text' | 'interactive' | 'template' | 'media' | 'tagged-text';
+export interface SimSend {
+    channel: string;
+    kind: SimSendKind;
+    detail: string;
+}
+export type SimInboundInput = {
+    text: string;
+} | {
+    interactive: {
+        id: string;
+        title?: string;
+    };
+} | {
+    button: {
+        payload: string;
+        text?: string;
+    };
+};
+export interface Simulator {
+    send(channel: string, threadId: string, input: SimInboundInput): Promise<SimSend[]>;
+    window(threadId: string): Promise<{
+        open: boolean;
+        expiresAt: Date | null;
+    }>;
+    sends(channel?: string): SimSend[];
+    readonly platforms: Record<string, PlatformClient>;
+    readonly router: ReturnType<typeof createMessagingRouter>;
+}
+export interface CreateSimulatorOptions {
+    runtime: Runtime;
+    bridge: EngagementBridge;
+    channels: string[];
+    windowStore: WindowStore;
+    defaultCustomerId?: (threadId: string) => string;
+}
+export declare function createSimulator(opts: CreateSimulatorOptions): Simulator;

package/dist/simulator.js

@@ -0,0 +1,161 @@
+import { createMessagingRouter } from '@kuralle-agents/messaging';
+function renderInteractiveDetail(interactive) {
+    const body = interactive.body;
+    if (interactive.action.type === 'buttons') {
+        const opts = interactive.action.buttons.map((b) => `(${b.id}:${b.title})`).join('');
+        return `[buttons] ${body} :: ${opts}`;
+    }
+    if (interactive.action.type === 'list') {
+        const rows = interactive.action.sections
+            .flatMap((s) => s.rows.map((r) => `(${r.id}:${r.title})`))
+            .join('');
+        const listBtn = interactive.action.button;
+        return `[list] ${body} :: ${listBtn} :: ${rows}`;
+    }
+    return `[${interactive.action.type}] ${body}`;
+}
+function renderMediaDetail(media) {
+    const cap = media.caption ? ` caption=${media.caption}` : '';
+    return `${media.type}/${media.mimeType}${cap}`;
+}
+function createRecordingPlatform(channel, allSends) {
+    const handlers = [];
+    let seq = 0;
+    const makeResult = (threadId) => ({
+        messageId: `sim-${channel}-${seq++}`,
+        threadId,
+        timestamp: new Date(),
+    });
+    const record = (kind, detail) => {
+        allSends.push({ channel, kind, detail });
+    };
+    return {
+        platform: channel,
+        handleWebhook: async () => new Response('OK'),
+        onMessage: (handler) => {
+            handlers.push(handler);
+        },
+        onStatus: () => { },
+        onReaction: () => { },
+        sendText: async (_to, text) => {
+            record('text', text);
+            return makeResult(_to);
+        },
+        sendTextWithTag: async (_to, text, tag) => {
+            record('tagged-text', `${text}[tag=${tag}]`);
+            return makeResult(_to);
+        },
+        sendTemplate: async (_to, template) => {
+            record('template', template.name);
+            return makeResult(_to);
+        },
+        sendInteractive: async (_to, interactive) => {
+            record('interactive', renderInteractiveDetail(interactive));
+            return makeResult(_to);
+        },
+        sendMedia: async (_to, media) => {
+            record('media', renderMediaDetail(media));
+            return makeResult(_to);
+        },
+        sendRaw: async (_to) => makeResult(_to),
+        markAsRead: async () => { },
+        sendTypingIndicator: async () => { },
+        uploadMedia: async () => ({ mediaId: 'mock' }),
+        downloadMedia: async () => ({ data: Buffer.from(''), mimeType: 'text/plain' }),
+        formatConverter: {
+            toPlainText: (t) => t,
+            toMarkdown: (t) => t,
+            toPlatformFormat: (t) => t,
+        },
+        webhookRouter: () => {
+            throw new Error('webhook not used in simulator');
+        },
+        deliver: async (message) => {
+            for (const handler of handlers) {
+                await handler(message, message);
+            }
+        },
+    };
+}
+function buildInboundMessage(channel, threadId, customerId, messageId, input) {
+    const base = {
+        id: messageId,
+        platform: channel,
+        threadId,
+        customerId,
+        from: { id: customerId, name: 'Simulator' },
+        timestamp: new Date(),
+    };
+    if ('text' in input) {
+        return { ...base, type: 'text', text: input.text };
+    }
+    if ('button' in input) {
+        if (channel === 'instagram') {
+            return {
+                ...base,
+                type: 'interactive',
+                button: { payload: input.button.payload, text: input.button.text ?? input.button.payload },
+            };
+        }
+        return {
+            ...base,
+            type: 'text',
+            text: input.button.payload,
+        };
+    }
+    const { id, title } = input.interactive;
+    if (channel === 'whatsapp' || channel === 'instagram') {
+        return {
+            ...base,
+            type: 'interactive',
+            interactive: { type: 'button_reply', id, title: title ?? id },
+        };
+    }
+    return {
+        ...base,
+        type: 'text',
+        text: id,
+    };
+}
+export function createSimulator(opts) {
+    const allSends = [];
+    const platforms = {};
+    const clients = {};
+    for (const channel of opts.channels) {
+        const client = createRecordingPlatform(channel, allSends);
+        clients[channel] = client;
+        platforms[channel] = client;
+    }
+    const router = createMessagingRouter({
+        runtime: opts.runtime,
+        platforms,
+        windowStore: opts.windowStore,
+        ...opts.bridge,
+    });
+    const customerFor = opts.defaultCustomerId ?? ((threadId) => threadId);
+    let inboundSeq = 0;
+    return {
+        platforms,
+        router,
+        async send(channel, threadId, input) {
+            const client = clients[channel];
+            if (!client) {
+                throw new Error(`Simulator channel "${channel}" is not configured`);
+            }
+            const start = allSends.length;
+            const messageId = `in-${++inboundSeq}`;
+            const customerId = customerFor(threadId);
+            await client.deliver(buildInboundMessage(channel, threadId, customerId, messageId, input));
+            return allSends.slice(start);
+        },
+        async window(threadId) {
+            const state = await opts.windowStore.get(threadId);
+            return { open: state.open, expiresAt: state.expiresAt };
+        },
+        sends(channel) {
+            if (channel === undefined)
+                return [...allSends];
+            return allSends.filter((s) => s.channel === channel);
+        },
+    };
+}

package/dist/strategist-middleware.d.ts

@@ -0,0 +1,3 @@
+import type { OutboundMiddleware } from '@kuralle-agents/messaging';
+import type { SmartSendStrategist } from './strategist.js';
+export declare function strategistMiddleware(strategist: SmartSendStrategist): OutboundMiddleware;

package/dist/strategist-middleware.js

@@ -0,0 +1,19 @@
+export function strategistMiddleware(strategist) {
+    return {
+        name: 'strategist',
+        async send(req, next) {
+            if (req.payload.kind !== 'text')
+                return next(req);
+            const input = { text: req.payload.text, window: req.meta.window };
+            const decision = await strategist.decide(input);
+            switch (decision.kind) {
+                case 'freeform':
+                    return next(req);
+                case 'template':
+                    return next({ ...req, payload: { kind: 'template', template: decision.template } });
+                case 'defer':
+                    return { kind: 'deferred', reason: decision.reason };
+            }
+        },
+    };
+}

package/dist/strategist.d.ts

@@ -0,0 +1,67 @@
+import type { OutboundTemplate, WindowState } from '@kuralle-agents/messaging';
+export interface TemplateDescriptor {
+    name: string;
+    language: string;
+    category: 'authentication' | 'marketing' | 'utility';
+    status: 'APPROVED' | 'PENDING' | 'REJECTED';
+    quality: 'GREEN' | 'YELLOW' | 'RED' | 'PAUSED' | 'DISABLED' | 'UNKNOWN';
+    params: {
+        key: string;
+        required: boolean;
+    }[];
+}
+export type DeferReason = 'no-approved-template' | 'no-template-fit' | 'param-validation-failed' | 'selector-error' | (string & {});
+export interface ConversionAudit {
+    requestedText: string;
+    chosenTemplate: string;
+    params: Record<string, string>;
+    at: number;
+}
+export type SendDecision = {
+    kind: 'freeform';
+    text: string;
+} | {
+    kind: 'template';
+    template: OutboundTemplate;
+    selected: TemplateDescriptor;
+    audit: ConversionAudit;
+} | {
+    kind: 'defer';
+    reason: DeferReason;
+};
+export interface StrategistInput {
+    text: string;
+    window: WindowState;
+    intent?: string;
+    flowState?: Readonly<Record<string, unknown>>;
+}
+export interface TemplateSelector {
+    select(input: {
+        text: string;
+        intent?: string;
+        candidates: readonly TemplateDescriptor[];
+        flowState?: Readonly<Record<string, unknown>>;
+    }): Promise<{
+        name: string;
+        language: string;
+        params: Record<string, string>;
+    } | null>;
+}
+export interface TemplateCatalog {
+    approved(): Promise<TemplateDescriptor[]>;
+    validateParams(name: string, p: Record<string, string>): {
+        ok: boolean;
+        errors?: string[];
+    };
+}
+export interface AuditSink {
+    record(a: ConversionAudit): Promise<void> | void;
+}
+export interface SmartSendStrategist {
+    decide(input: StrategistInput): Promise<SendDecision>;
+}
+export declare function createSmartSendStrategist(opts: {
+    catalog: TemplateCatalog;
+    selector: TemplateSelector;
+    audit: AuditSink;
+}): SmartSendStrategist;

package/dist/strategist.js

@@ -0,0 +1,55 @@
+export function createSmartSendStrategist(opts) {
+    const { catalog, selector, audit } = opts;
+    return {
+        async decide(input) {
+            if (input.window.open) {
+                return { kind: 'freeform', text: input.text };
+            }
+            const candidates = await catalog.approved();
+            if (candidates.length === 0) {
+                return { kind: 'defer', reason: 'no-approved-template' };
+            }
+            let pick;
+            try {
+                pick = await selector.select({
+                    text: input.text,
+                    intent: input.intent,
+                    candidates,
+                    flowState: input.flowState,
+                });
+            }
+            catch {
+                return { kind: 'defer', reason: 'selector-error' };
+            }
+            if (pick == null) {
+                return { kind: 'defer', reason: 'no-template-fit' };
+            }
+            const selected = candidates.find((c) => c.name === pick.name);
+            if (!selected) {
+                return { kind: 'defer', reason: 'no-template-fit' };
+            }
+            const v = catalog.validateParams(pick.name, pick.params);
+            if (!v.ok) {
+                return { kind: 'defer', reason: 'param-validation-failed' };
+            }
+            const conversionAudit = {
+                requestedText: input.text,
+                chosenTemplate: pick.name,
+                params: pick.params,
+                at: Date.now(),
+            };
+            await audit.record(conversionAudit);
+            const template = {
+                name: pick.name,
+                language: pick.language,
+                namedParams: pick.params,
+            };
+            return {
+                kind: 'template',
+                template,
+                selected,
+                audit: conversionAudit,
+            };
+        },
+    };
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@kuralle-agents/engagement",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kuralle/kuralle-agents.git",
+    "directory": "packages/kuralle-engagement"
+  },
+  "version": "0.3.0",
+  "description": "Channel-agnostic engagement layer for Kuralle agents (window-safe outbound, smart-send, interactive fidelity, handoff, consent, proactive).",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "ai": "^6.0.0",
+    "zod": "^3.24.2",
+    "@kuralle-agents/core": "0.3.0",
+    "@kuralle-agents/messaging-meta": "0.3.0",
+    "@kuralle-agents/messaging": "0.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.2",
+    "@types/node": "^22.13.4"
+  },
+  "scripts": {
+    "prebuild": "rm -rf dist",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "test": "bun test"
+  }
+}