@kuralle-agents/engagement 0.8.0 → 0.9.0

package/README.md

@@ -96,6 +96,8 @@ import { whatsappPolicy, webPolicy, instagramPolicy } from '@kuralle-agents/enga
 - **`sessionConsentStore` / `consentGate`** — opt-in/opt-out and STOP handling (customer-keyed).
 - **`sessionOwnershipStore` / `ownershipGate`** — bot vs human thread ownership; human-owned inbound does not run flows.
 - **`createBroadcasts` / `createDrip`** — campaign ledger idempotency and drip schedules (see exports in `src/index.ts`).
+- **`createOwnershipEscalationHandler` / `resolveEscalation`** — the channel side of `HarnessConfig.escalation`: claim the thread for the human + notify on escalation; release + resume the bot (with the resolution in context) when the human is done.
+- The `Scheduler` contract is owned by `@kuralle-agents/core` (re-exported here) — drips, broadcasts, and runtime wake turns (`RunOptions.wake`) share backends: in-process timers in dev, Cloudflare DO alarms via `@kuralle-agents/cf-agent`.
 
 ## Example
 

package/dist/escalation.d.ts

@@ -0,0 +1,38 @@
+import type { EscalationHandler, EscalationOutcome, EscalationRequest } from '@kuralle-agents/core';
+import type { OwnershipStore } from '@kuralle-agents/messaging';
+/**
+ * Channel-side escalation bridge: when the runtime escalates, claim thread
+ * ownership for the human (so `ownershipGate` suppresses bot sends) and
+ * notify the human channel; when the human is done, `resolveEscalation`
+ * releases ownership and hands the conversation back to the bot with the
+ * resolution in context.
+ */
+export interface EscalationBridgeOptions {
+    ownership: OwnershipStore;
+    /** Map the escalation to the channel threadId to claim. Default: `request.sessionId`. */
+    threadIdFor?: (request: EscalationRequest) => string;
+    /**
+     * Notify the human side (inbox, Slack, pager). The returned outcome is
+     * surfaced to the runtime; returning nothing defaults to
+     * `{ status: 'queued', queueId: sessionId }`.
+     */
+    notify?: (request: EscalationRequest) => Promise<EscalationOutcome | void>;
+}
+export declare function createOwnershipEscalationHandler(options: EscalationBridgeOptions): EscalationHandler;
+/** The runtime surface `resolveEscalation` needs (satisfied by `Runtime`). */
+export interface EscalationResumable {
+    resumeFromEscalation(sessionId: string, opts?: {
+        resolutionSummary?: string;
+    }): Promise<void>;
+}
+export interface ResolveEscalationOptions {
+    runtime: EscalationResumable;
+    ownership: OwnershipStore;
+    sessionId: string;
+    /** Channel threadId that was claimed. Default: `sessionId`. */
+    threadId?: string;
+    /** What the human did — appended to the conversation so the bot resumes with context. */
+    resolutionSummary?: string;
+}
+/** Human is done: release the thread back to the bot and resume the run with context. */
+export declare function resolveEscalation(options: ResolveEscalationOptions): Promise<void>;

package/dist/escalation.js

@@ -0,0 +1,20 @@
+export function createOwnershipEscalationHandler(options) {
+    return async (request) => {
+        const threadId = options.threadIdFor?.(request) ?? request.sessionId;
+        await options.ownership.claim(threadId, 'human');
+        if (options.notify) {
+            const outcome = await options.notify(request);
+            if (outcome) {
+                return outcome;
+            }
+        }
+        return { status: 'queued', queueId: request.sessionId };
+    };
+}
+/** Human is done: release the thread back to the bot and resume the run with context. */
+export async function resolveEscalation(options) {
+    await options.ownership.release(options.threadId ?? options.sessionId);
+    await options.runtime.resumeFromEscalation(options.sessionId, {
+        resolutionSummary: options.resolutionSummary,
+    });
+}

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export { aiTemplateSelector } from './selector.js';
 export type { OutboundTemplateComponent } from '@kuralle-agents/messaging';
 export { webPolicy } from './policies/web.js';
 export { sessionOwnershipStore, ownershipGate, OWNERSHIP_WM_KEY, } from './ownership.js';
+export { createOwnershipEscalationHandler, resolveEscalation, type EscalationBridgeOptions, type EscalationResumable, type ResolveEscalationOptions, } from './escalation.js';
 export { sessionConsentStore, consentGate, CONSENT_WM_KEY } from './consent.js';
 export { createInProcessScheduler, type Scheduler, type SendJob, } from './scheduler.js';
 export { createInMemoryBroadcastLedger, createRedisBroadcastLedger, type BroadcastLedger, } from './broadcast-ledger.js';

package/dist/index.js

@@ -15,6 +15,7 @@ export { whatsappTemplateCatalog, mapTemplateInfoToDescriptor, isApprovedNonPaus
 export { aiTemplateSelector } from './selector.js';
 export { webPolicy } from './policies/web.js';
 export { sessionOwnershipStore, ownershipGate, OWNERSHIP_WM_KEY, } from './ownership.js';
+export { createOwnershipEscalationHandler, resolveEscalation, } from './escalation.js';
 export { sessionConsentStore, consentGate, CONSENT_WM_KEY } from './consent.js';
 export { createInProcessScheduler, } from './scheduler.js';
 export { createInMemoryBroadcastLedger, createRedisBroadcastLedger, } from './broadcast-ledger.js';

package/dist/interactive-renderer.d.ts

@@ -1,19 +1,4 @@
-import type { ChoiceOption } from '@kuralle-agents/core';
-import type { InteractiveMessage, OutboundMiddleware } from '@kuralle-agents/messaging';
+import type { OutboundMiddleware } from '@kuralle-agents/messaging';
 import type { ChannelPolicy } from './policy.js';
-/** WhatsApp reply-button title limit (R-11). */
-export declare const BUTTON_TITLE_MAX = 20;
-/** WhatsApp list row title limit (R-11). */
-export declare const LIST_ROW_TITLE_MAX = 24;
-/** WhatsApp reply buttons per message. */
-export declare const BUTTON_COUNT_MAX = 3;
-/** WhatsApp list rows per message. */
-export declare const LIST_ROW_COUNT_MAX = 10;
-/**
- * Renders author choices to a channel-neutral `InteractiveMessage`, enforcing
- * WhatsApp limits (R-11). URL options map to a single-button reply shape because
- * `InteractiveMessage` has no dedicated CTA variant — the sink must interpret
- * `ChoiceOption.url` when sending platform CTA messages.
- */
-export declare function renderChoices(options: ChoiceOption[], prompt: string): InteractiveMessage;
+export { renderChoices, BUTTON_TITLE_MAX, LIST_ROW_TITLE_MAX, BUTTON_COUNT_MAX, LIST_ROW_COUNT_MAX, } from '@kuralle-agents/messaging';
 export declare function interactiveRenderer(policies?: ChannelPolicy[]): OutboundMiddleware;

package/dist/interactive-renderer.js

@@ -1,105 +1,8 @@
-/** WhatsApp reply-button title limit (R-11). */
-export const BUTTON_TITLE_MAX = 20;
-/** WhatsApp list row title limit (R-11). */
-export const LIST_ROW_TITLE_MAX = 24;
-/** WhatsApp reply buttons per message. */
-export const BUTTON_COUNT_MAX = 3;
-/** WhatsApp list rows per message. */
-export const LIST_ROW_COUNT_MAX = 10;
-function assertButtonTitle(label, optionId) {
-    if (label.length > BUTTON_TITLE_MAX) {
-        throw new Error(`interactive: button title for "${optionId}" exceeds ${BUTTON_TITLE_MAX} characters (got ${label.length})`);
-    }
-}
-function assertListRowTitle(label, optionId) {
-    if (label.length > LIST_ROW_TITLE_MAX) {
-        throw new Error(`interactive: list row title for "${optionId}" exceeds ${LIST_ROW_TITLE_MAX} characters (got ${label.length})`);
-    }
-}
-/**
- * Renders author choices to a channel-neutral `InteractiveMessage`, enforcing
- * WhatsApp limits (R-11). URL options map to a single-button reply shape because
- * `InteractiveMessage` has no dedicated CTA variant — the sink must interpret
- * `ChoiceOption.url` when sending platform CTA messages.
- */
-export function renderChoices(options, prompt) {
-    if (options.length === 0) {
-        throw new Error('interactive: at least one option is required');
-    }
-    const flowOption = options.find((o) => o.flow);
-    if (flowOption) {
-        if (options.length > 1) {
-            throw new Error('interactive: flow messages support exactly one option');
-        }
-        const { flowId } = flowOption.flow;
-        if (!flowOption.flow.cta) {
-            throw new Error('interactive: flow option requires flow.cta');
-        }
-        return {
-            type: 'flow',
-            body: prompt,
-            action: {
-                type: 'flow',
-                flowId,
-                flowToken: flowOption.id,
-            },
-        };
-    }
-    if (options.some((o) => o.url)) {
-        const urlOptions = options.filter((o) => o.url);
-        if (urlOptions.length > BUTTON_COUNT_MAX) {
-            throw new Error(`interactive: too many URL options (max ${BUTTON_COUNT_MAX} reply buttons)`);
-        }
-        for (const o of urlOptions) {
-            assertButtonTitle(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 > LIST_ROW_COUNT_MAX) {
-        throw new Error(`interactive: too many options (max ${LIST_ROW_COUNT_MAX} list rows)`);
-    }
-    if (options.length <= BUTTON_COUNT_MAX) {
-        for (const o of options) {
-            assertButtonTitle(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) {
-        assertListRowTitle(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,
-                    })),
-                },
-            ],
-        },
-    };
-}
+// Canonical ChoiceOption -> InteractiveMessage rendering now lives in
+// @kuralle-agents/messaging (the default stream mapper uses it too);
+// re-exported here for existing engagement consumers.
+export { renderChoices, BUTTON_TITLE_MAX, LIST_ROW_TITLE_MAX, BUTTON_COUNT_MAX, LIST_ROW_COUNT_MAX, } from '@kuralle-agents/messaging';
+import { renderChoices } from '@kuralle-agents/messaging';
 function policyFor(policies, platform) {
     return policies.find((p) => p.channel === platform);
 }

package/dist/scheduler.d.ts

@@ -1,27 +1,12 @@
-/** 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.
+ * The scheduler contract is owned by `@kuralle-agents/core` — one interface
+ * for engagement send-jobs and runtime wake turns (broadcasts, drips, and
+ * proactive agent-initiated messages share backends: in-process timers in
+ * dev, DO alarms on Cloudflare, any queue in between). Re-exported here so
+ * existing engagement consumers keep their import path.
  */
-export declare function createInProcessScheduler(opts: {
-    run: (job: SendJob) => void | Promise<void>;
-    timer?: InjectableTimer;
-}): Scheduler;
+import type { ScheduledJob } from '@kuralle-agents/core';
+export { createInProcessScheduler } from '@kuralle-agents/core';
+export type { Scheduler, InjectableTimer } from '@kuralle-agents/core';
+/** A unit of deferred engagement work (broadcast step / drip step). */
+export type SendJob = ScheduledJob;

package/dist/scheduler.js

@@ -1,36 +1 @@
-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);
-        },
-    };
-}
+export { createInProcessScheduler } from '@kuralle-agents/core';

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-engagement"
   },
-  "version": "0.8.0",
+  "version": "0.9.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",
@@ -27,9 +27,9 @@
   "dependencies": {
     "ai": "^6.0.0",
     "zod": "^4.0.0",
-    "@kuralle-agents/core": "0.8.0",
-    "@kuralle-agents/messaging": "0.8.0",
-    "@kuralle-agents/messaging-meta": "0.8.0"
+    "@kuralle-agents/core": "0.9.0",
+    "@kuralle-agents/messaging": "0.9.0",
+    "@kuralle-agents/messaging-meta": "0.9.0"
   },
   "devDependencies": {
     "typescript": "^5.8.2",