@kuralle-agents/engagement 0.8.0 → 0.8.5

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/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.8.5",
   "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.8.5",
+    "@kuralle-agents/messaging-meta": "0.8.5",
+    "@kuralle-agents/messaging": "0.8.5"
   },
   "devDependencies": {
     "typescript": "^5.8.2",