@voctiv/agent-sdk 0.2.14 → 0.2.15

package/README.md

@@ -70,6 +70,48 @@ export default defineScript(async ({ channel, logger, context }) => {
 });
 ```
 
+## Examples
+
+The [`examples/`](./examples/) folder contains copy-paste-ready scripts:
+
+| Example | Description |
+|---------|-------------|
+| [outbound-with-recall.ts](./examples/outbound-with-recall.ts) | Outbound with `recallCount` / `recallDelay` (automatic redial on failure) |
+| [recall-routing-by-attempt.ts](./examples/recall-routing-by-attempt.ts) | Online recall: branch on `context.attempt` (`getScriptPhase` → `'online'`) |
+| [schedule-call-with-defaults.ts](./examples/schedule-call-with-defaults.ts) | `platform.call()` without explicit recall — CMS defaults from `context` |
+| [after-call-continuation.ts](./examples/after-call-continuation.ts) | `onSuccessCall` / `onFailedCall` vs recall (mutually exclusive) |
+| [read-recall-from-params.ts](./examples/read-recall-from-params.ts) | `parseRecallDelaySeconds()` / `parseRecallCount()` on legacy params |
+
+### Quick recall example
+
+```ts
+import { defineScript } from '@voctiv/agent-sdk';
+
+export default defineScript(async ({ channel, context, platform, logger }) => {
+  channel.sip.answer();
+
+  if ((context.attempt ?? 0) > 0) {
+    logger.log('Online recall attempt', { attempt: context.attempt });
+    await channel.audio.say('Sorry we missed you earlier. Trying again now.');
+  }
+
+  // Schedule first outbound with up to 3 retries, 5 min apart (no entryPoint — same defineScript runs each leg).
+  await platform.call(context.msisdn!, {
+    recallCount: context.recallCount ?? 3,
+    recallDelay: context.recallDelay ?? 300,
+  });
+});
+```
+
+Parse legacy time strings from params when needed:
+
+```ts
+import { parseRecallDelaySeconds, parseRecallCount } from '@voctiv/agent-sdk';
+
+const delaySec = parseRecallDelaySeconds(context.dialogParams?.recall_delay); // "00:05:00" → 300
+const maxAttempts = parseRecallCount(context.dialogParams?.recall_count);
+```
+
 ## What The SDK Contains
 
 `defineScript(fn)` marks the default export as the script entry point. It returns the same function and exists to give TypeScript the correct `ScriptContext` shape.
@@ -895,19 +937,74 @@ return {
 **Do not** return `env` from the script. Persist state via `context.env$`; the runtime snapshots it
 after completion into **`PersistedScriptResult.env`**.
 
-Use **`getScriptPhase(context)`** to branch on lifecycle (`online`, `messaging`, `recall`, etc.):
+## Script Lifecycle (`getScriptPhase`)
+
+The host always runs your single **`defineScript` export** — there is no separate runtime entry per
+name (unlike logic-executor Python `run_unit(entry_point=...)`). Use **`getScriptPhase(context)`**
+to tell *why* the script is running now: live call, pre-call queue, post-call continuation,
+messaging, etc.
+
+**`context.headless === true` only means “no live SIP/media”.** It does **not** tell you whether
+the run is before or after a call. For that, use `getScriptPhase`.
+
+| Phase | `context.headless` | When | Typical `context.entryPoint` |
+|-------|-------------------|------|--------------------------------|
+| `before_call` | `true` | Dialog queue / bulk outbound **before** the first platform call (often schedules `platform.call`) | empty, `main`, `default` |
+| `online` | `false` | Live SIP session (inbound, outbound, **and automatic recall redials**) | any (ignored for phase) |
+| `after_call_success` | `true` | Headless run **after** a successful call | `on_success_call`, `after_call_success`, `on_done_call` |
+| `after_call_failed` | `true` | Headless run **after** failed attempts (when `onFailedCall` was configured) | `on_failed_call`, `after_call_failed` |
+| `messaging` | `true` | Inbound message triggered the run | `on_message_api_received`, or `context.inboundMessage` set |
+| `recall` | `true` | Headless recall leg (legacy `entry_point`) | `on_recall`, `recall` |
+| `headless_other` | `true` | Any other headless run with a custom `entry_point` | your custom name |
+
+**Automatic recall** (`recallCount` + `recallDelay`) creates new **online** SIP legs with an
+incremented `context.attempt`. Branch with `(context.attempt ?? 0) > 0`, **not** `phase === 'recall'`.
+See [examples/recall-routing-by-attempt.ts](./examples/recall-routing-by-attempt.ts).
+
+**After-call continuation** uses `onSuccessCall` / `onFailedCall` on `platform.call()`. When the call
+ends, the host sets `dialog.params.entry_point` to that handler name and runs the same `defineScript`
+headlessly. See [examples/after-call-continuation.ts](./examples/after-call-continuation.ts).
+
+These two failure models are **mutually exclusive** on one scheduled outbound — see
+[Failed outbound: automatic recall vs after-call continuation](#failed-outbound-automatic-recall-vs-after-call-continuation).
 
 ```ts
 import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
 
-export default defineScript(async ({ context }) => {
-  switch (getScriptPhase(context)) {
-    case 'online':
-      // live call
-      break;
+export default defineScript(async ({ channel, context, logger, platform }) => {
+  const phase = getScriptPhase(context);
+
+  switch (phase) {
+    case 'before_call':
+      // Headless pre-call: queue worker, usually schedules outbound.
+      await platform.call(context.msisdn!, { recallCount: 3, recallDelay: 300 });
+      return { output: { phase } };
+
+    case 'after_call_success':
+      logger.log('Post-call success branch', { entryPoint: context.entryPoint });
+      return { output: { phase } };
+
+    case 'after_call_failed':
+      logger.log('Post-call failure branch', { entryPoint: context.entryPoint });
+      platform.dialog.result = 'done';
+      return { output: { phase } };
+
     case 'messaging':
-      // inbound message handling
-      break;
+      logger.log('Inbound message', { text: context.inboundMessage?.payload });
+      return { output: { phase } };
+
+    case 'online':
+      channel.sip.answer();
+      if ((context.attempt ?? 0) > 0) {
+        logger.log('Online recall leg', { attempt: context.attempt });
+      }
+      await channel.audio.say('Hello.');
+      return;
+
+    default:
+      // headless_other, recall (headless), etc.
+      logger.log('Other headless run', { phase, entryPoint: context.entryPoint });
+      return { output: { phase } };
   }
 });
 ```
@@ -956,23 +1053,10 @@ By default, the platform schedules the call for immediate processing. Use `date`
 ```ts
 await platform.call('+12025551234', {
   date: new Date(Date.now() + 15 * 60_000),
-  entryPoint: 'on_callback',
 });
 ```
 
-`entryPoint` is passed to the script when the scheduled call starts. Use it to route the callback into a specific branch:
-
-```ts
-export default defineScript(async ({ context, channel }) => {
-  if (context.entryPoint === 'on_callback') {
-    channel.sip.answer();
-    await channel.audio.say('Hello, this is your scheduled callback.');
-    return;
-  }
-
-  await channel.audio.say('I will call you back in fifteen minutes.');
-});
-```
+When the scheduled call connects, the host runs your **`defineScript` export** again. Branch inside that handler if needed (there is no separate runtime entry per name, unlike logic-executor Python `run_unit(entry_point=...)`).
 
 Use `dateEnd` to define the latest time when the call is still useful. If the platform cannot place the call before that deadline, it can skip the attempt.
 
@@ -980,33 +1064,90 @@ Use `dateEnd` to define the latest time when the call is still useful. If the pl
 await platform.call('+12025551234', {
   date: new Date('2026-04-29T10:00:00Z'),
   dateEnd: new Date('2026-04-29T10:30:00Z'),
-  entryPoint: 'on_reminder',
 });
 ```
 
-Retries are controlled with `recallCount` and `recallDelay`:
+Retries are controlled with `recallCount` and `recallDelay` (delay is always **seconds** in SDK options):
 
 ```ts
 await platform.call('+12025551234', {
-  entryPoint: 'on_follow_up',
   recallCount: 3,
-  recallDelay: 300,
+  recallDelay: 300, // 5 minutes between failed outbound attempts
+});
+```
+
+This schedules automatic redials: on each **failed outbound** the host creates a new platform call
+with `date_added = now + recallDelay`. The dialer runs the script again with an incremented
+`context.attempt`. See [examples/outbound-with-recall.ts](./examples/outbound-with-recall.ts).
+
+### Failed outbound: automatic recall vs after-call continuation
+
+After a failed **outbound** call the platform must choose **one** failure-handling strategy.
+`recallCount` + `recallDelay` and `onFailedCall` answer the same question in different ways, so
+they are **mutually exclusive** on `platform.call()` (logic-executor `nn.call` parity).
+
+| Strategy | `platform.call()` options | What happens on failure | Next script run |
+|----------|---------------------------|-------------------------|-----------------|
+| **Automatic recall** | `recallCount` + `recallDelay` (both required on the `call` row) | Host schedules another outbound `call` after `recallDelay`; bumps `dialog.params.attempt` | **Online** SIP leg — same `defineScript`, branch on `context.attempt` |
+| **After-call continuation** | `onFailedCall` (and optionally `onSuccessCall`) | Host sets `dialog.params.entry_point` to the handler name and re-queues the dialog | **Headless** run — `getScriptPhase(context)` → `after_call_failed` |
+
+**Why not both?** Recall is fully platform-driven (dialer redials without running your script between
+attempts). `onFailedCall` is script-driven (your handler decides logging, CRM, manual retry, etc.).
+If both were written to `call.params`, shutdown would be ambiguous. This host therefore **keeps
+`onFailedCall` and drops recall** at schedule time so the outbound still starts and the after-call
+branch runs on failure. (If both somehow land on an existing `call.params` row, recall still wins
+at shutdown — avoid writing both.)
+
+**Do not** pass `onFailedCall` together with `recallCount` and `recallDelay` in the same
+`platform.call()` invocation. If both are present (script options, dialog params, or CMS
+defaults), the host **keeps `onFailedCall` and drops recall** so the call still schedules —
+after-call continuation wins over automatic redial. Prefer configuring only one strategy
+explicitly.
+
+**Host default resolution:** when you omit recall options, the host may default them from
+`context.recallCount` / `context.recallDelay` (CMS contact-rules). That auto-fill applies only when
+the script did **not** pass explicit `onFailedCall` in `platform.call()` options.
+`onFailedCall` / `onSuccessCall` are **never** invented from `dialog.params` or Omni
+`scheduleOutbound` defaults — they are script kwargs only (LE `nn.call` parity). Stale
+`on_failed_call` left in dialog params must not block CMS recall.
+
+Diagram-style legacy outbound (Megafon converter) typically uses `onFailedCall` plus
+`on_failed_call_system` (sleep + call the main block again) — **not** CMS automatic recall.
+See [examples/after-call-continuation.ts](./examples/after-call-continuation.ts).
+
+Use either automatic recall **or** offline `onFailedCall` continuation — not both on one scheduled
+outbound leg.
+
+Branch inside the script on recall attempts (`context.attempt`, not a separate entry function):
+
+```ts
+import { defineScript } from '@voctiv/agent-sdk';
+
+export default defineScript(async ({ channel, context, logger }) => {
+  channel.sip.answer();
+
+  if ((context.attempt ?? 0) > 0) {
+    logger.log('Recall leg', { attempt: context.attempt });
+    await channel.audio.say('Follow-up call. Please hold.');
+  }
 });
 ```
 
-This means the platform may retry up to three times, waiting about five minutes between attempts.
+See [examples/recall-routing-by-attempt.ts](./examples/recall-routing-by-attempt.ts).
 
-When you omit these options, the host fills defaults from `context.recallCount` / `context.recallDelay`
-(effective values for the current dialog). Those in turn fall back to CMS agent contact-rules
+When you omit recall options, the host fills them from `context.recallCount` / `context.recallDelay`
+(effective values for the current dialog) **only when `onFailedCall` is not configured** for that
+scheduled call. Those values fall back to CMS agent contact-rules
 (`context.agent?.recallCount` / `context.agent?.recallDelay`, legacy `nn.get_recall_count()` /
-`nn.get_recall_delay()`).
+`nn.get_recall_delay()`). See [Failed outbound: automatic recall vs after-call continuation](#failed-outbound-automatic-recall-vs-after-call-continuation).
 
 Other scheduling options:
 
 - `priority`: higher-priority calls can be processed earlier by the dialer.
 - `timezone`: timezone offset used by the platform when interpreting scheduled dates.
-- `onSuccessCall`: entry point to use after a successful call.
-- `onFailedCall`: entry point to use after failed attempts.
+- `onSuccessCall`: headless handler name after a successful call (e.g. `'on_success_call'` → `getScriptPhase` `'after_call_success'`).
+- `onFailedCall`: headless handler name after failed attempts (mutually exclusive with recall).
+- `entryPoint` (optional): stored as `entry_point` in call params for LE DB compatibility. The host still runs the same `defineScript` export; use `context.entryPoint` only if **you** branch on it inside the handler.
 - `protoAdditional`: extra protocol-level parameters, such as SIP headers expected by your telephony setup.
 
 ### Messaging
@@ -1025,9 +1166,14 @@ await platform.messaging.send({
 
 Offline, or headless, sessions run a script without a live SIP call, WebSocket audio stream, RTP pipeline, ASR, or TTS playback. They are used for platform-driven background logic, queued dialog processing, and messaging events.
 
-The script entry point is still the same `defineScript()` handler. Detect this mode with `context.headless`:
+The script entry point is still the same `defineScript()` handler. Detect offline mode with
+`context.headless`, then use **`getScriptPhase(context)`** to distinguish pre-call queue runs
+(`before_call`) from post-call continuations (`after_call_success` / `after_call_failed`). See
+[Script Lifecycle (`getScriptPhase`)](#script-lifecycle-getscriptphase).
 
 ```ts
+import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+
 export default defineScript(async ({ channel, context, logger, platform }) => {
   if (!context.headless) {
     channel.sip.answer();
@@ -1035,12 +1181,24 @@ export default defineScript(async ({ channel, context, logger, platform }) => {
     return;
   }
 
+  const phase = getScriptPhase(context);
   logger.log('Running offline logic', {
+    phase,
     dialogUuid: context.dialogUuid,
     entryPoint: context.entryPoint,
   });
 
-  // Offline logic usually works with text, params, env, NLU, LLM, and platform APIs.
+  if (phase === 'before_call') {
+    await platform.call(context.msisdn!);
+    return;
+  }
+
+  if (phase === 'after_call_success' || phase === 'after_call_failed') {
+    // Post-call headless branch — see examples/after-call-continuation.ts
+    return { output: { phase } };
+  }
+
+  // messaging, headless_other, etc.
 });
 ```
 
@@ -1143,9 +1301,7 @@ export default defineScript(async ({ channel, context, platform }) => {
     const text = String(context.inboundMessage?.payload?.text ?? '');
 
     if (text.includes('call me')) {
-      await platform.call(context.msisdn, {
-        entryPoint: 'on_callback',
-      });
+      await platform.call(context.msisdn);
     }
 
     return { output: { handledOffline: true } };
@@ -1182,19 +1338,25 @@ Recall behavior uses **two layers** on `context`:
 | Layer | Fields | Source | Use when |
 |-------|--------|--------|----------|
 | Agent defaults | `context.agent?.recallCount`, `context.agent?.recallDelay` | CMS contact-rules (`agent.recall_count`, `agent.delay` → seconds) | Compare with CMS settings; legacy `nn.get_recall_count()` / `get_recall_delay()` parity |
-| Effective for this run | `context.recallCount`, `context.recallDelay` | `dialog.params` / `call.params`, then agent defaults | Schedule outbound calls, recall routing logic |
+| Effective for this run | `context.recallCount`, `context.recallDelay` | `dialog.params` / `call.params`, then agent defaults | Read in script; pass explicitly to `platform.call()` when using **automatic recall** |
 
 Precedence for effective values: **dialog/call params** (`recall_count`, `recall_delay`) **>** agent CMS defaults.
 
+**Important:** CMS/effective recall on `context` does **not** mean every `platform.call()` gets
+automatic recall. The host copies recall onto the scheduled `call` row only when you omit recall
+options **and** `onFailedCall` is not configured (see
+[Failed outbound: automatic recall vs after-call continuation](#failed-outbound-automatic-recall-vs-after-call-continuation)).
+Agents with both CMS contact-rules and diagram `on_failed_call` handlers use the after-call path;
+recall fields on `context` are informational unless your script passes them explicitly.
+
 `context.attempt` is the current recall attempt counter from `dialog.params.attempt` (starts at 0).
 `context.entryPoint` is the routing branch for this run (e.g. after a failed call).
 
 ```ts
 // Use effective values when scheduling the next outbound leg
-await context.platform?.call?.(msisdn, {
+await platform.call(context.msisdn!, {
   recallCount: context.recallCount,
   recallDelay: context.recallDelay,
-  entryPoint: 'on_follow_up',
 });
 
 // Log CMS defaults vs per-dialog override
@@ -1235,8 +1397,8 @@ Important fields:
 - `context.flag`: business flag.
 - `context.initialData`: shallow snapshot of params at script start.
 - `context.dialogParams`: live param map for the run.
-- `context.entryPoint`: current routing entry point.
-- `context.attempt`: current recall attempt number (`dialog.params.attempt`).
+- `context.entryPoint`: current routing entry point (see [Script Lifecycle](#script-lifecycle-getscriptphase)).
+- `context.attempt`: current recall attempt number (`dialog.params.attempt`; use with `phase === 'online'`).
 - `context.recallCount` / `context.recallDelay`: effective recall settings for this dialog/call.
 - `context.agent?.recallCount` / `context.agent?.recallDelay`: CMS agent defaults (immutable snapshot).
 - `context.headless`: true for offline/queue/messaging sessions without a real media channel.
@@ -1282,7 +1444,10 @@ Headless channels are for offline, queue, or messaging sessions:
 - `createAsr()` returns an inert handle.
 - LLM, NLU, messaging, platform calls, dialog state, and `env$` still work.
 
-Use `context.headless` to branch when a script must behave differently without a real media channel. See [Offline / Headless Logic](#offline--headless-logic) for details and examples.
+Use `context.headless` plus `getScriptPhase(context)` when a script must behave differently without a
+real media channel or across pre-call / post-call headless runs. See
+[Offline / Headless Logic](#offline--headless-logic) and
+[Script Lifecycle (`getScriptPhase`)](#script-lifecycle-getscriptphase).
 
 ## Text Input For Tests
 

package/dist/index.d.ts

@@ -33,6 +33,7 @@ export type { ScriptDialogContext, ScriptPhase, ScriptRunTime, ScriptResult, Per
 export { getScriptPhase } from './types/script-context';
 export type { NluScriptApi, PlatformApi, DialogApi, ScheduleCallOptions, SendMessageOptions, InboundMessage, MessagingApi, } from './types/platform';
 export type { ScriptLogger } from './types/logger';
+export { TranscriptionRole } from './types/logger';
 export type { MediaChannel, ChannelAudio, ChannelEvents, } from './types/media-channel';
 export type { ChannelLlm, LlmOptions, LlmStreamChunk, ExtractOptions, PersistentLlmStreamHandle, } from './types/llm';
 export type { ChannelSip, SipState, SipProgressEvent, SipInviteHeaders, ParsedSdpDetails, } from './types/sip';
@@ -44,4 +45,5 @@ export { LEGACY_PHRASE_RECORD_BRAND, isLegacyPhraseRecord, } from './types/legac
 export type { TextInput } from './types/text-input';
 export type { DtmfEvent, SipInfo, SipSignal, DataMessage, } from './types/events';
 export type { NluExtractOptions, NluInferResult } from './types/nlu';
+export { parseRecallCount, parseRecallDelaySeconds } from './recall-utils';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE/D,YAAY,EACV,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,YAAY,GACb,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,UAAU,EACV,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACjG,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3H,YAAY,EACV,kBAAkB,EAClB,sBAAsB,EACtB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,YAAY,EACV,SAAS,EACT,OAAO,EACP,SAAS,EACT,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE/D,YAAY,EACV,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,YAAY,GACb,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,UAAU,EACV,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACjG,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3H,YAAY,EACV,kBAAkB,EAClB,sBAAsB,EACtB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,YAAY,EACV,SAAS,EACT,OAAO,EACP,SAAS,EACT,WAAW,GACZ,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -29,12 +29,17 @@
  * and live SIP INFO ({@link import('./types/events').SipInfo} on `sipInfo$`). See **`README.md`** → SIP Signalling Metadata.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isLegacyPhraseRecord = exports.LEGACY_PHRASE_RECORD_BRAND = exports.getScriptPhase = exports.defineScript = void 0;
+exports.parseRecallDelaySeconds = exports.parseRecallCount = exports.isLegacyPhraseRecord = exports.LEGACY_PHRASE_RECORD_BRAND = exports.TranscriptionRole = exports.getScriptPhase = exports.defineScript = void 0;
 var define_script_1 = require("./define-script");
 Object.defineProperty(exports, "defineScript", { enumerable: true, get: function () { return define_script_1.defineScript; } });
 var script_context_1 = require("./types/script-context");
 Object.defineProperty(exports, "getScriptPhase", { enumerable: true, get: function () { return script_context_1.getScriptPhase; } });
+var logger_1 = require("./types/logger");
+Object.defineProperty(exports, "TranscriptionRole", { enumerable: true, get: function () { return logger_1.TranscriptionRole; } });
 var legacy_phrase_1 = require("./types/legacy-phrase");
 Object.defineProperty(exports, "LEGACY_PHRASE_RECORD_BRAND", { enumerable: true, get: function () { return legacy_phrase_1.LEGACY_PHRASE_RECORD_BRAND; } });
 Object.defineProperty(exports, "isLegacyPhraseRecord", { enumerable: true, get: function () { return legacy_phrase_1.isLegacyPhraseRecord; } });
+var recall_utils_1 = require("./recall-utils");
+Object.defineProperty(exports, "parseRecallCount", { enumerable: true, get: function () { return recall_utils_1.parseRecallCount; } });
+Object.defineProperty(exports, "parseRecallDelaySeconds", { enumerable: true, get: function () { return recall_utils_1.parseRecallDelaySeconds; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AAEH,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AAerB,yDAAwD;AAA/C,gHAAA,cAAc,OAAA;AA4CvB,uDAG+B;AAF7B,2HAAA,0BAA0B,OAAA;AAC1B,qHAAA,oBAAoB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AAEH,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AAerB,yDAAwD;AAA/C,gHAAA,cAAc,OAAA;AAavB,yCAAmD;AAA1C,2GAAA,iBAAiB,OAAA;AAgC1B,uDAG+B;AAF7B,2HAAA,0BAA0B,OAAA;AAC1B,qHAAA,oBAAoB,OAAA;AAUtB,+CAA2E;AAAlE,gHAAA,gBAAgB,OAAA;AAAE,uHAAA,uBAAuB,OAAA"}

package/dist/recall-utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Parse recall delay to seconds — parity with logic-executor `agent.delay` / `recall_delay`
+ * in call params (`HH:mm:ss`, integer seconds).
+ */
+export declare function parseRecallDelaySeconds(value: unknown): number | undefined;
+/** Parse recall attempt limit from call/dialog params. */
+export declare function parseRecallCount(value: unknown): number | undefined;
+//# sourceMappingURL=recall-utils.d.ts.map

package/dist/recall-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-utils.d.ts","sourceRoot":"","sources":["../src/recall-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CA4B1E;AAED,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAWnE"}

package/dist/recall-utils.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRecallDelaySeconds = parseRecallDelaySeconds;
+exports.parseRecallCount = parseRecallCount;
+/**
+ * Parse recall delay to seconds — parity with logic-executor `agent.delay` / `recall_delay`
+ * in call params (`HH:mm:ss`, integer seconds).
+ */
+function parseRecallDelaySeconds(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+        return Math.floor(value);
+    }
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    if (/^\d+$/.test(trimmed)) {
+        return parseInt(trimmed, 10);
+    }
+    const match = trimmed.match(/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/);
+    if (!match)
+        return undefined;
+    const hours = parseInt(match[1], 10);
+    const minutes = parseInt(match[2], 10);
+    const seconds = match[3] ? parseInt(match[3], 10) : 0;
+    if (!Number.isFinite(hours) ||
+        !Number.isFinite(minutes) ||
+        !Number.isFinite(seconds)) {
+        return undefined;
+    }
+    return hours * 3600 + minutes * 60 + seconds;
+}
+/** Parse recall attempt limit from call/dialog params. */
+function parseRecallCount(value) {
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+        return Math.floor(value);
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed)
+            return undefined;
+        const n = parseInt(trimmed, 10);
+        if (Number.isFinite(n) && n >= 0)
+            return n;
+    }
+    return undefined;
+}
+//# sourceMappingURL=recall-utils.js.map

package/dist/recall-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-utils.js","sourceRoot":"","sources":["../src/recall-utils.ts"],"names":[],"mappings":";;AAIA,0DA4BC;AAGD,4CAWC;AA9CD;;;GAGG;AACH,SAAgB,uBAAuB,CAAC,KAAc;IACpD,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACtE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAEhD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAE/B,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1B,OAAO,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAChE,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAE7B,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,IACE,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QACvB,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;QACzB,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EACzB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,GAAG,IAAI,GAAG,OAAO,GAAG,EAAE,GAAG,OAAO,CAAC;AAC/C,CAAC;AAED,0DAA0D;AAC1D,SAAgB,gBAAgB,CAAC,KAAc;IAC7C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACtE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QAC/B,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAChC,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/types/logger.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Role for {@link ScriptLogger.transcript} lines that land in the CMS call transcript.
+ *
+ * Wire values stay `'user'` / `'agent'` for dialog-consumer mapping
+ * (`human_phrase` / `agent_phrase`).
+ */
+export declare enum TranscriptionRole {
+    User = "user",
+    Agent = "agent"
+}
 /**
  * Structured logger available to scripts.
  *
@@ -15,6 +25,26 @@ export interface ScriptLogger {
     error(message: string, data?: Record<string, unknown>): void;
     /** Debug-level log entry; intended for process/debug stream output rather than legacy DB stats. */
     debug(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Write a phrase into the CMS call transcript.
+     *
+     * In Voctiv legacy mode:
+     * - {@link TranscriptionRole.User} → `nv.listen` / `stop` in `dialog_stats` (Mongo `human_phrase`)
+     * - {@link TranscriptionRole.Agent} → `nv.synthesize` (Mongo `agent_phrase`)
+     *
+     * Also logs as `USER: …` / `AGENT: …`. Empty / whitespace-only text is ignored.
+     *
+     * Does **not** mutate the script's `call_transcript` output entity — scripts
+     * that keep their own transcript buffer should still update it explicitly.
+     *
+     * @example
+     * ```ts
+     * import { TranscriptionRole } from '@lib/scripting-sdk';
+     * logger.transcript(TranscriptionRole.User, userText);
+     * logger.transcript(TranscriptionRole.Agent, '¿Hola?');
+     * ```
+     */
+    transcript(role: TranscriptionRole, message: string): void;
     /**
      * Enable real-time log streaming to a remote debug endpoint.
      * Opens a Socket.IO connection from this API pod to the debug server.

package/dist/types/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/types/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3D,+BAA+B;IAC/B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,6BAA6B;IAC7B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,mGAAmG;IACnG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE7D;;;;;;OAMG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpC,kEAAkE;IAClE,YAAY,IAAI,IAAI,CAAC;IAErB;;;;;;;;;OASG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9E"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/types/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,oBAAY,iBAAiB;IAC3B,IAAI,SAAS;IACb,KAAK,UAAU;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3D,+BAA+B;IAC/B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,6BAA6B;IAC7B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,mGAAmG;IACnG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE7D;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3D;;;;;;OAMG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpC,kEAAkE;IAClE,YAAY,IAAI,IAAI,CAAC;IAErB;;;;;;;;;OASG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9E"}

package/dist/types/logger.js

@@ -1,3 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TranscriptionRole = void 0;
+/**
+ * Role for {@link ScriptLogger.transcript} lines that land in the CMS call transcript.
+ *
+ * Wire values stay `'user'` / `'agent'` for dialog-consumer mapping
+ * (`human_phrase` / `agent_phrase`).
+ */
+var TranscriptionRole;
+(function (TranscriptionRole) {
+    TranscriptionRole["User"] = "user";
+    TranscriptionRole["Agent"] = "agent";
+})(TranscriptionRole || (exports.TranscriptionRole = TranscriptionRole = {}));
 //# sourceMappingURL=logger.js.map

package/dist/types/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/types/logger.ts"],"names":[],"mappings":""}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/types/logger.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACH,IAAY,iBAGX;AAHD,WAAY,iBAAiB;IAC3B,kCAAa,CAAA;IACb,oCAAe,CAAA;AACjB,CAAC,EAHW,iBAAiB,iCAAjB,iBAAiB,QAG5B"}

package/dist/types/platform.d.ts

@@ -42,9 +42,12 @@ export interface ScheduleCallOptions {
     /** Deadline — don't call after this time. */
     dateEnd?: string | Date;
     /**
-     * Entry point to pass to the script when the call connects.
+     * Optional label stored in call params as `entry_point` (LE DB compatibility).
      *
-     * Stored in the created call params as `entry_point`.
+     * The host always runs your single `defineScript` export — it does **not** invoke a
+     * separate function by this name (unlike logic-executor Python `run_unit(entry_point=...)`).
+     * Use {@link import('./script-context').ScriptDialogContext.entryPoint} inside the handler
+     * if you branch manually (e.g. headless after-call via {@link getScriptPhase}).
      */
     entryPoint?: string;
     /**
@@ -61,18 +64,38 @@ export interface ScheduleCallOptions {
      */
     channel?: string | number;
     /**
-     * How many times to retry on failure. Stored as `recall_count` in call params.
-     * When omitted, the host defaults from {@link import('./script-context').ScriptDialogContext.recallCount}.
+     * Max failed-call retries. Stored as `recall_count` in call params.
+     * When omitted, the host defaults from {@link import('./script-context').ScriptDialogContext.recallCount}
+     * only if {@link onFailedCall} is not configured for this scheduled call.
+     *
+     * Activates **automatic recall**: on each failed outbound the dialer schedules another call after
+     * {@link recallDelay} and increments `context.attempt`. Mutually exclusive with {@link onFailedCall}
+     * — if both are present, the host keeps {@link onFailedCall} and drops recall. Requires both
+     * `recallCount` and `recallDelay` on the `call` row when used alone.
      */
     recallCount?: number;
     /**
-     * Delay in seconds between retries. Stored as `recall_delay` in call params.
-     * When omitted, the host defaults from {@link import('./script-context').ScriptDialogContext.recallDelay}.
+     * Delay before the next recall attempt, in **seconds**.
+     * Stored as `recall_delay` in call params (numeric seconds from SDK; LE may also
+     * use `HH:MM:SS` strings in legacy rows — the host normalizes both on schedule).
+     *
+     * When omitted, the host defaults from {@link import('./script-context').ScriptDialogContext.recallDelay}
+     * only if {@link onFailedCall} is not configured for this scheduled call.
+     *
+     * Mutually exclusive with {@link onFailedCall}.
      */
     recallDelay?: number;
     /** Entry point to use after a successful call. Stored as `on_success_call`. */
     onSuccessCall?: string;
-    /** Entry point to use after a failed call. Stored as `on_failed_call`. */
+    /**
+     * Headless handler after a failed outbound. Stored as `on_failed_call`.
+     *
+     * Activates **after-call continuation**: the host sets `dialog.params.entry_point` and re-runs this
+     * script with `getScriptPhase` → `after_call_failed`. Mutually exclusive with automatic recall
+     * ({@link recallCount} + {@link recallDelay}) on the same `platform.call()`. If both are present,
+     * the host keeps this option and drops recall. When set (including via Omni `scheduleOutbound`
+     * defaults), CMS recall is not auto-copied onto the `call` row.
+     */
     onFailedCall?: string;
     /** Call priority (higher = processed sooner by dialer). */
     priority?: number;
@@ -100,7 +123,7 @@ export interface ScheduleCallOptions {
  * are logged. There is no awaitable setter, so do not use it for transactional flow.
  */
 export interface DialogApi {
-    /** Current script entry point (e.g. `"on_recall"`). Set to change routing for the next call. */
+    /** Value from `dialog.params.entry_point` — for branching inside `defineScript`, not a separate runtime entry. */
     entryPoint: string | undefined;
     /** Dialog outcome (e.g. `"done"`, `"busy"`, `"no_answer"`). Set to finalize dialog. */
     result: string | undefined;

package/dist/types/platform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/types/platform.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/types/platform.ts"],"names":[],"mappings":"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"}

package/dist/types/script-context.d.ts

@@ -145,7 +145,7 @@ export interface ScriptDialogContext {
      * {@link import('./mixer').PlayOptions} to select **`key_storage.name`** when LE credential maps exist.
      */
     availableMediaKeys?: string[];
-    /** Script entry point for routing (e.g. `"on_recall"`, `"on_message_api_received"`). */
+    /** Script routing hint from `dialog.params.entry_point` — branch inside `defineScript`; not a separate host entry. */
     entryPoint?: string;
     /** Current recall attempt number for this dialog (from `dialog.params.attempt`, starts at 0). */
     attempt?: number;
@@ -154,8 +154,9 @@ export interface ScriptDialogContext {
      *
      * Resolved at script start: `dialog.params` / `call.params` (`recall_count`) override
      * {@link AgentContext.recallCount} from CMS. Omitted when no value is configured.
-     * Passed to {@link import('./platform').ScheduleCallOptions.recallCount} when scheduling
-     * outbound calls without explicit options.
+     * The host may default {@link import('./platform').ScheduleCallOptions.recallCount} from this
+     * field when scheduling outbound calls without explicit recall options and without
+     * {@link import('./platform').ScheduleCallOptions.onFailedCall}.
      */
     recallCount?: number;
     /**
@@ -163,7 +164,9 @@ export interface ScriptDialogContext {
      *
      * Resolved at script start: `dialog.params` / `call.params` (`recall_delay`) override
      * {@link AgentContext.recallDelay} from CMS (`agent.delay` converted to seconds).
-     * Omitted when no value is configured.
+     * Omitted when no value is configured. The host may default
+     * {@link import('./platform').ScheduleCallOptions.recallDelay} from this field under the same
+     * conditions as {@link recallCount}.
      */
     recallDelay?: number;
     /**

package/dist/types/script-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"script-context.d.ts","sourceRoot":"","sources":["../../src/types/script-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"script-context.d.ts","sourceRoot":"","sources":["../../src/types/script-context.ts"],"names":[],"mappings":"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"}

package/dist/types/script-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"script-context.js","sourceRoot":"","sources":["../../src/types/script-context.ts"],"names":[],"mappings":";;AAoQA,wCAcC;AApCD,MAAM,+BAA+B,GAAG,IAAI,GAAG,CAAC;IAC9C,iBAAiB;IACjB,oBAAoB;IACpB,cAAc;CACf,CAAC,CAAC;AACH,MAAM,8BAA8B,GAAG,IAAI,GAAG,CAAC;IAC7C,gBAAgB;IAChB,mBAAmB;CACpB,CAAC,CAAC;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,SAAgB,cAAc,CAAC,OAA4B;IACzD,IAAI,CAAC,OAAO,CAAC,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAEvC,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;IAE1D,IAAI,+BAA+B,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,oBAAoB,CAAC;IACzE,IAAI,8BAA8B,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,mBAAmB,CAAC;IACvE,IAAI,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,QAAQ,CAAC;IACjD,IAAI,EAAE,KAAK,yBAAyB,IAAI,OAAO,CAAC,cAAc;QAC5D,OAAO,WAAW,CAAC;IAErB,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,MAAM,IAAI,EAAE,KAAK,SAAS;QAAE,OAAO,aAAa,CAAC;IAEnE,OAAO,gBAAgB,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"script-context.js","sourceRoot":"","sources":["../../src/types/script-context.ts"],"names":[],"mappings":";;AAuQA,wCAcC;AApCD,MAAM,+BAA+B,GAAG,IAAI,GAAG,CAAC;IAC9C,iBAAiB;IACjB,oBAAoB;IACpB,cAAc;CACf,CAAC,CAAC;AACH,MAAM,8BAA8B,GAAG,IAAI,GAAG,CAAC;IAC7C,gBAAgB;IAChB,mBAAmB;CACpB,CAAC,CAAC;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,SAAgB,cAAc,CAAC,OAA4B;IACzD,IAAI,CAAC,OAAO,CAAC,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAEvC,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;IAE1D,IAAI,+BAA+B,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,oBAAoB,CAAC;IACzE,IAAI,8BAA8B,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,mBAAmB,CAAC;IACvE,IAAI,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,QAAQ,CAAC;IACjD,IAAI,EAAE,KAAK,yBAAyB,IAAI,OAAO,CAAC,cAAc;QAC5D,OAAO,WAAW,CAAC;IAErB,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,MAAM,IAAI,EAAE,KAAK,SAAS;QAAE,OAAO,aAAa,CAAC;IAEnE,OAAO,gBAAgB,CAAC;AAC1B,CAAC"}

package/examples/README.md

@@ -0,0 +1,43 @@
+# SDK usage examples
+
+Runnable-style snippets for `@voctiv/agent-sdk`. Copy into your script project or use as reference.
+
+Each file exports one `defineScript` handler. The host **always** invokes that single export — unlike logic-executor Python, it does **not** call separate functions by `entry_point` name.
+
+| File | Topic |
+|------|--------|
+| [outbound-with-recall.ts](./outbound-with-recall.ts) | Outbound with `recallCount` / `recallDelay` |
+| [recall-routing-by-attempt.ts](./recall-routing-by-attempt.ts) | Branch on `context.attempt` during online recall legs |
+| [schedule-call-with-defaults.ts](./schedule-call-with-defaults.ts) | `platform.call()` using CMS defaults from `context` |
+| [after-call-continuation.ts](./after-call-continuation.ts) | `onSuccessCall` / `onFailedCall` + `getScriptPhase()` |
+| [read-recall-from-params.ts](./read-recall-from-params.ts) | `parseRecallDelaySeconds()` / `parseRecallCount()` |
+
+## Recall flow
+
+1. Script calls `platform.call(msisdn, { recallCount, recallDelay })`.
+2. Host stores params on the `call` row.
+3. On failed outbound, host schedules a new `call` with `date_added = now + recallDelay`.
+4. Dialer runs the **same script** again; `context.attempt` is incremented.
+5. Branch inside `defineScript` with `context.attempt`, not with a separate entry function.
+
+Do **not** combine step 1 with `onFailedCall` on the same `platform.call()` — use one strategy per
+scheduled outbound leg. See [after-call-continuation.ts](./after-call-continuation.ts) for the
+script-driven failure path (`after_call_failed`).
+
+## Failed outbound: pick one strategy
+
+| Need | Use | Avoid on the same `platform.call()` |
+|------|-----|--------------------------------------|
+| CMS-style automatic redials | `recallCount` + `recallDelay` (or omit both and let host default from `context` when no `onFailedCall`) | `onFailedCall` |
+| Diagram / custom logic after failure | `onFailedCall` (+ branch on `getScriptPhase` → `after_call_failed`) | `recallCount` + `recallDelay` |
+
+When `onFailedCall` is passed **explicitly** in `platform.call()` options, the host does
+**not** auto-apply CMS `context.recallCount` / `context.recallDelay` to the new `call` row.
+`on_failed_call` in dialog/Omni defaults is ignored for scheduling. If the script passes both
+strategies in options, the host **drops recall** and keeps `onFailedCall`.
+
+## `entryPoint` vs logic-executor
+
+In LE Python, `entry_point='main'` selects which script function runs.
+
+In this host, `platform.call({ entryPoint })` only writes `entry_point` to DB params and sets `context.entryPoint` so **your** `defineScript` can branch (e.g. `getScriptPhase(context)` for headless after-call). Omit it when recall/online logic uses `context.attempt` only.

package/examples/after-call-continuation.ts

@@ -0,0 +1,47 @@
+/**
+ * After-call routing with `onSuccessCall` / `onFailedCall` (headless continuation).
+ *
+ * Mutually exclusive with automatic recall (`recallCount` + `recallDelay`) on the same
+ * `platform.call()`. If both are passed, the host keeps `onFailedCall` and drops recall.
+ *
+ * When `onFailedCall` is set, CMS `context.recallCount` / `context.recallDelay` are not
+ * auto-applied to the scheduled `call` row; the after-call branch runs on failure instead.
+ *
+ * On call end the host sets `dialog.params.entry_point` to the configured handler name
+ * and runs the **same** `defineScript` export headlessly. Branch with
+ * `getScriptPhase(context)` (`after_call_success` / `after_call_failed`).
+ */
+import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+
+export default defineScript(async ({ channel, context, logger, platform }) => {
+  const phase = getScriptPhase(context);
+
+  if (context.headless && phase === 'after_call_failed') {
+    logger.log('Post-call offline branch after failed outbound');
+    await platform.messaging.send({
+      src: 'bot',
+      destination: context.msisdn || '',
+      text: 'Sorry we missed you. Reply to reschedule.',
+    });
+    platform.dialog.result = 'done';
+    return { output: { phase } };
+  }
+
+  if (context.headless && phase === 'after_call_success') {
+    logger.log('Post-call offline branch after successful call');
+    return { output: { phase } };
+  }
+
+  channel.sip.answer();
+  await channel.audio.say('Starting outbound attempt.');
+
+  const msisdn = context.msisdn || context.callerId;
+  if (!msisdn) return;
+
+  await platform.call(msisdn, {
+    onSuccessCall: 'on_success_call',
+    onFailedCall: 'on_failed_call',
+  });
+
+  logger.log('Scheduled outbound with after-call headless handlers (no automatic recall)');
+});

package/examples/outbound-with-recall.ts

@@ -0,0 +1,43 @@
+/**
+ * Schedule an outbound call that the platform will retry on failure.
+ *
+ * The host runs a single `defineScript` handler — there is no separate runtime
+ * entry per `entry_point` like logic-executor Python `run_unit(entry_point=...)`.
+ * Recall legs are the same script again with an incremented `context.attempt`.
+ *
+ * Do not combine recall options with `onFailedCall` on the same `platform.call()`.
+ * When `onFailedCall` is configured, CMS recall is not auto-applied to the call row.
+ * See README § "Failed outbound: automatic recall vs after-call continuation".
+ */
+import { defineScript } from '@voctiv/agent-sdk';
+
+const RECALL_COUNT = 3;
+/** Delay between failed attempts, in seconds (5 minutes). */
+const RECALL_DELAY_SEC = 300;
+
+export default defineScript(async ({ channel, context, logger, platform }) => {
+  channel.sip.answer();
+
+  const msisdn = context.msisdn || context.callerId;
+  if (!msisdn) {
+    logger.error('No msisdn on context');
+    return;
+  }
+
+  await channel.audio.say(
+    'We will call you back shortly. If we cannot reach you, we will retry a few times.',
+  );
+
+  await platform.call(msisdn, {
+    recallCount: RECALL_COUNT,
+    recallDelay: RECALL_DELAY_SEC,
+  });
+
+  logger.log('Outbound scheduled with recall', {
+    msisdn,
+    recallCount: RECALL_COUNT,
+    recallDelaySec: RECALL_DELAY_SEC,
+  });
+
+  return { output: { scheduled: true } };
+});

package/examples/read-recall-from-params.ts

@@ -0,0 +1,41 @@
+/**
+ * Read recall settings from legacy dialog/call params and schedule outbound.
+ */
+import {
+  defineScript,
+  parseRecallCount,
+  parseRecallDelaySeconds,
+} from '@voctiv/agent-sdk';
+
+export default defineScript(async ({ context, logger, platform }) => {
+  const params = context.dialogParams ?? {};
+
+  const rawCount = params.recall_count ?? params.recallCount;
+  const rawDelay = params.recall_delay ?? params.recallDelay;
+
+  const recallCount =
+    parseRecallCount(rawCount) ?? context.recallCount ?? context.agent?.recallCount;
+  const recallDelaySec =
+    parseRecallDelaySeconds(rawDelay) ??
+    context.recallDelay ??
+    context.agent?.recallDelay;
+
+  logger.log('Parsed recall from params', {
+    rawCount,
+    rawDelay,
+    recallCount,
+    recallDelaySec,
+    attempt: context.attempt,
+  });
+
+  const msisdn = context.msisdn || context.callerId;
+  if (!msisdn || recallCount == null || recallDelaySec == null) {
+    logger.warn('Missing msisdn or recall config — skipping schedule');
+    return;
+  }
+
+  await platform.call(msisdn, {
+    recallCount,
+    recallDelay: recallDelaySec,
+  });
+});

package/examples/recall-routing-by-attempt.ts

@@ -0,0 +1,55 @@
+/**
+ * Handle the first outbound attempt vs automatic recall attempts.
+ *
+ * Recall calls are still **online** SIP sessions (`getScriptPhase` → `'online'`).
+ * Use `context.attempt` (from `dialog.params.attempt`, starts at 0) to branch inside
+ * your single `defineScript` handler — the host does not invoke a separate function.
+ */
+import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+
+export default defineScript(async ({ channel, context, logger }) => {
+  const phase = getScriptPhase(context);
+  const attempt = context.attempt ?? 0;
+
+  logger.log('Call leg', {
+    phase,
+    attempt,
+    headless: context.headless,
+    recallCount: context.recallCount,
+    recallDelay: context.recallDelay,
+  });
+
+  channel.sip.answer();
+
+  if (!context.headless && attempt > 0) {
+    await channel.audio.say(
+      `This is follow-up attempt number ${attempt + 1}. Please stay on the line.`,
+    );
+  } else if (!context.headless) {
+    await channel.audio.say('Hello, this is our first call to you today.');
+  }
+
+  const asr = await channel.createAsr({ language: context.language || 'ru-RU' });
+
+  return new Promise((resolve) => {
+    asr.result$.subscribe(async (text) => {
+      if (!text.trim()) return;
+
+      if (/voicemail|leave a message/i.test(text)) {
+        logger.log('Voicemail detected — host may schedule recall', { attempt });
+        channel.sip.hangup();
+        resolve({ output: { outcome: 'voicemail', attempt } });
+        return;
+      }
+
+      await channel.audio.say('Thank you. Goodbye.');
+      channel.sip.hangup();
+      resolve({ output: { outcome: 'answered', attempt } });
+    });
+
+    channel.events.terminated$.subscribe(() => {
+      asr.destroy();
+      resolve({ output: { outcome: 'terminated', attempt } });
+    });
+  });
+});

package/examples/schedule-call-with-defaults.ts

@@ -0,0 +1,31 @@
+/**
+ * Schedule outbound using CMS contact-rules defaults already resolved on `context`.
+ *
+ * When `recallCount` / `recallDelay` are omitted from `platform.call()` options, the host
+ * fills them from `context.recallCount` / `context.recallDelay` only when `onFailedCall` is
+ * not configured for that scheduled call.
+ */
+import { defineScript } from '@voctiv/agent-sdk';
+
+export default defineScript(async ({ channel, context, logger, platform }) => {
+  channel.sip.answer();
+
+  const msisdn = context.msisdn || context.callerId;
+  if (!msisdn) return;
+
+  logger.log('Recall configuration snapshot', {
+    effective: {
+      count: context.recallCount,
+      delaySec: context.recallDelay,
+    },
+    agentDefaults: {
+      count: context.agent?.recallCount,
+      delaySec: context.agent?.recallDelay,
+    },
+    attempt: context.attempt,
+  });
+
+  await platform.call(msisdn);
+
+  await channel.audio.say('We have scheduled a call using your agent recall settings.');
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voctiv/agent-sdk",
-  "version": "0.2.14",
+  "version": "0.2.15",
   "description": "Voctiv TypeScript agent SDK: defineScript and platform types for the voice/dialog scripting runtime.",
   "license": "UNLICENSED",
   "author": "",
@@ -23,7 +23,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "examples"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",