@voctiv/agent-sdk 0.2.14 → 0.2.16

package/README.md

@@ -70,10 +70,60 @@ 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.
 
+**Three different “context” names:**
+
+| Name | Meaning |
+| --- | --- |
+| `ScriptContext` | Top-level injection: `{ channel, logger, context, platform }` |
+| `context` (`ScriptDialogContext`) | Dialog identity, params, routing snapshot, `env$`, headless — see [Dialog Context](#dialog-context-and-persisted-env) |
+| `options.context` on `platform.nlu.extract` | Opaque NLU disambiguation string/JSON — **not** dialog context |
+
 `ScriptContext` is the top-level object passed to a script:
 
 - `channel` is the media channel for SIP, WS, ASR, TTS, audio playback, LLM, and structured data messages.
@@ -178,19 +228,43 @@ If the call terminates before media becomes available, deferred audio resolves a
 On **SIP channels**, `channel.sip` exposes raw signalling beyond call state — useful for
 carrier routing, diversion chains, and vendor SDP attributes.
 
+#### When to use what
+
+| Need | API | When |
+| --- | --- | --- |
+| Routing / identity / locale from the **inbound INVITE** (`Diversion`, `X-Trunk-Id`, `X-Neuro-UUID`, `X-language`, …) | `channel.sip.inviteSipHeaders` | Call **start** only (snapshot) |
+| Peer signal **during** the call (e.g. mid-call language in INFO body) | `channel.sip.sipInfo$` | After subscribe; each INFO |
+| DTMF digits | `channel.sip.dtmf$` | Prefer over parsing INFO |
+| SDP / codec / connection | `remoteSdp` / `getRemoteSdpDetails()` | May change (183 / 200 / re-INVITE) |
+| SIP response code / phrase (180, 486, …) | `sipSignal$` | Low-level; **no** response headers |
+| Live SIP headers on 200 / re-INVITE / BYE | — | **Not exposed** |
+
+Decision guide:
+
+- Value from the inbound INVITE at call start → `inviteSipHeaders`
+- Mid-call signal from peer INFO → `sipInfo$` (`contentType` + `body` only)
+- DTMF → `dtmf$`
+- Media description → `remoteSdp` / `getRemoteSdpDetails()`
+- Live SIP response headers → not available (`sipSignal$` has status/SDP only)
+
+**Locale pattern:** read start language from `inviteSipHeaders` (e.g. `X-language`). Mid-call changes only work if the peer puts the language in the INFO **body** — INFO SIP headers are not forwarded. Monolingual agents can ignore both and use `context.language` / config.
+
+Outbound INVITE headers you **send** go through `platform.call({ protoAdditional })` or `makeCall` options — not `inviteSipHeaders` (read-only inbound snapshot). SIP metadata does not auto-update `context` or `platform.dialog`.
+
 #### INVITE headers (`inviteSipHeaders`)
 
 Snapshot of SIP headers from an **inbound INVITE** at call setup. Includes standard and
-extension headers (`Diversion`, `P-Asserted-Identity`, `X-Trunk-Id`, `X-Neuro-UUID`, …).
+extension headers (`Diversion`, `P-Asserted-Identity`, `X-Trunk-Id`, `X-Neuro-UUID`, `X-language`, …).
 
 | Property | Updates during call? |
 | --- | --- |
-| `inviteSipHeaders` | **No** — INVITE snapshot only; outbound B-legs usually `undefined` |
+| `inviteSipHeaders` | **No** — INVITE snapshot only; outbound B-legs / WS / headless usually `undefined` |
 
 ```ts
 const h = channel.sip.inviteSipHeaders;
 const diversion = h?.Diversion; // string | string[] when multiple hops
 const trunkId = h?.['X-Trunk-Id'];
+const lang = h?.['X-language'];
 ```
 
 Header names match what the host stack exposes (case-sensitive). Duplicate headers become
@@ -217,7 +291,9 @@ attributes. It is not a full SDP validator — use `remoteSdp` when you need the
 
 #### SIP INFO (`sipInfo$`)
 
-Live stream of incoming SIP INFO messages (`contentType` + `body`). Prefer `dtmf$` for DTMF.
+Live stream of incoming SIP INFO messages. Each event is `{ contentType, body }` only —
+**INFO request headers are not exposed**. Prefer `dtmf$` for DTMF. Does not update
+`inviteSipHeaders`.
 
 ```ts
 channel.sip.sipInfo$.subscribe(({ contentType, body }) => {
@@ -251,11 +327,14 @@ the per-event `sdp` on `sipSignal$`.
 - `bridge(other)` to cross-connect two SIP channels.
 
 `makeCall()` and `bridge()` are supported on SIP channels. The returned B-leg is a full
-`MediaChannel` with the same API as the main channel. WS and headless channels do not create real SIP legs.
+`MediaChannel` with the same API as the main channel. WS and headless channels cannot create real SIP
+legs, so both methods **throw** there rather than returning an inert leg you could talk into
+unnoticed. Guard them with `context.headless` or `channel.type` when a script runs in both modes.
 
 ### `channel.sip` Reference
 
-SIP-only unless noted. WS/headless: most methods are no-ops; `state` behaves as synthetic `active`.
+SIP-only unless noted. WS/headless: most methods are no-ops and `state` behaves as synthetic
+`active`, except `makeCall()` and `bridge()`, which throw.
 
 | Member | Description |
 | --- | --- |
@@ -266,10 +345,10 @@ SIP-only unless noted. WS/headless: most methods are no-ops; `state` behaves as
 | `early$` | Emits once when RTP is up before final answer |
 | `answered$` | Emits once on 200 OK |
 | `dtmf$` | Remote DTMF digits (`DtmfEvent`: `digit`, `duration`) |
-| `sipInfo$` | Live incoming SIP INFO (`SipInfo`: `contentType`, `body`) |
-| `sipSignal$` | Low-level SIP stack events (`SipSignal`; `sdp` only on that callback) |
+| `sipInfo$` | Mid-call SIP INFO (`contentType` + `body` only; INFO headers not exposed) |
+| `sipSignal$` | Low-level stack events (`statusCode` / `statusPhrase` / optional `sdp`; no headers) |
 | `remoteSdp` | Latest negotiated remote SDP body; updates when new SDP arrives |
-| `inviteSipHeaders` | Inbound INVITE header snapshot (`SipInviteHeaders`); does not update |
+| `inviteSipHeaders` | Start-of-call inbound INVITE header snapshot; does not update |
 | `getRemoteSdpDetails()` | Parse `remoteSdp` → `ParsedSdpDetails` (session + `a=` attributes) |
 | `sendProgress()` | Inbound: send 183 Session Progress → `early` |
 | `waitForEarly()` | Await `early` or `active` (Promise) |
@@ -285,8 +364,8 @@ SIP-only unless noted. WS/headless: most methods are no-ops; `state` behaves as
 
 Prefer `dtmf$` over `sipInfo$` for DTMF. Prefer `state$` / `early$` / `answered$` over raw
 `sipSignal$` for call lifecycle. Use `remoteSdp` / `getRemoteSdpDetails()` for negotiated
-media description; use `inviteSipHeaders` for routing headers from the inbound INVITE.
-See **SIP Signalling Metadata** above.
+media description; use `inviteSipHeaders` for start-of-call INVITE headers and `sipInfo$`
+for mid-call INFO body. See **When to use what** under SIP Signalling Metadata above.
 
 ### SIP Bridge
 
@@ -550,7 +629,7 @@ When phrase persistence is enabled, `preload()` can store decoded audio for late
 
 `ttsStrategy` controls how text is chunked:
 
-- `sentence`: split on sentence boundaries and synthesize each sentence. This is the default.
+- `sentence`: split on sentence boundaries and synthesize each sentence. This is the default. Only one sentence is synthesized at a time; when synthesis of N finishes, N+1 starts immediately while N continues playing from the mixer queue. Sentence N is fired as soon as its text is complete — it never waits for sentence N+1. For ElevenLabs HTTP TTS, each request gets `previous_text` / `next_text` when those neighbor texts are already available (e.g. full string already split); on an LLM stream typically only `previous_text` is known at fire time. Scripts do not need to set these fields. `eleven_v3` does not support those fields (API 400), so they are omitted for that model. The TTS cache key is still the sentence text only (neighbors are not part of the key), so cache hits may replay audio synthesized under a different neighbor context.
 - `streaming`: send chunks incrementally for streaming-capable vendors.
 - `full`: accumulate the whole input and synthesize it as one segment after the input completes.
 
@@ -889,25 +968,82 @@ return {
 };
 ```
 
-- **`output`** — stored in dialog stats / host persistence.
+- **`output`** — stored in dialog stats / host persistence. This is **not** the LE `dialog.result` lifecycle column — that is `platform.dialog.result` (see [Dialog State](#dialog-state)).
 - **`error`** — optional; usually auto-populated on crash, but scripts may set it explicitly.
 
 **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`.
+
+The return value is the `ScriptPhase` union — one of the phases in the table below.
+
+| 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 } };
   }
 });
 ```
@@ -916,7 +1052,7 @@ export default defineScript(async ({ context }) => {
 
 `platform` exposes platform operations.
 
-`platform.nlu.extract(utterance, options?)` runs intent/entity extraction. If `options.context` is omitted, current dialog params are serialized and used as NLU context.
+`platform.nlu.extract(utterance, options?)` runs intent/entity extraction. If `options.context` is omitted or `null`, the runtime sends **no** NLU context — there is no auto-fill from dialog params or `flag`. Pass it explicitly when needed (logic-executor scripts usually pass `context.flag`). Default NLU language comes from the LE agent (`_nlu.language`), not `context.lang`.
 
 `platform.nlu.extract$()` is an Observable wrapper — one `extract()` call per subscription, not a streaming NLU session.
 
@@ -924,20 +1060,64 @@ export default defineScript(async ({ context }) => {
 const result = await platform.nlu.extract('I want to reschedule', {
   intents: ['reschedule', 'cancel'],
   entities: ['date', 'time'],
+  context: context.flag,
   use_synonyms: true,
 });
 ```
 
-Platform APIs (`platform.nlu`, `platform.call`, dialog writes, messaging, phrase records) are available when the host enables platform integration.
+Platform APIs (`platform.nlu`, `platform.call`, dialog writes, messaging, phrase records) are available when the host enables platform integration (`context.legacyV3Compat`).
 
 ### Dialog State
 
+`platform.dialog` reads and writes the LE **dialog row** — not SIP media and not the script return value.
+
+#### What `platform.dialog.result` is
+
+`platform.dialog.result` maps to the PostgreSQL column **`dialog.result`**: the **lifecycle status** of the dialog entity in the CMS / offline queue (in queue, in progress, closed). It is **not** the outcome of a SIP leg.
+
+| Value | Meaning |
+| --- | --- |
+| `null` | Often after-call continuation: dialog re-enters queue-api, then becomes `queued` |
+| `queued` | In the offline queue, not yet claimed |
+| `pending` | In progress (live SIP/WS or claimed queue row) |
+| `done` | Dialog closed successfully (terminal for the pipeline) |
+| `error` | Dialog closed with a logic/runtime error |
+
+The **host** also moves these statuses (live session → `pending`; shutdown without continuation → often `done` / `error`; automatic recall → `pending`; after-call chain → `null` + `entry_point` in params). Scripts set `platform.dialog.result` when they want to **explicitly** fix the LE dialog status (commonly `'done'` in a headless after-call handler). That does **not** replace `channel.sip.hangup()`.
+
+#### Do not confuse
+
+| API | Layer | Does | Does not |
+| --- | --- | --- | --- |
+| `platform.dialog.result` | LE `dialog` row | Lifecycle status (`done`, `pending`, …) | Hang up SIP; equal `call.result`; equal `ScriptResult.output` |
+| `platform.dialog.entryPoint` | LE `dialog.params` | Persist routing hint for later headless/queue runs | Change SIP state; select another script export |
+| `context.entryPoint` | `ScriptDialogContext` | **Snapshot** of `entry_point` at script start (`getScriptPhase`) | Persist if you assign it — write via `platform.dialog.entryPoint` |
+| `return { output }` / `ScriptResult` | Script return | dialog_stats / host dump | LE `dialog.result` column |
+| `channel.sip.hangup()` / `terminated$` | Media leg | End or observe SIP/WS media | Set `platform.dialog.result` by itself |
+| `call.result` (LE call row) | Per-call | SIP terminal code/phrase for CMS logs | Same as `dialog.result` |
+
+There is no `context.result` field — read/write dialog lifecycle only through `platform.dialog.result`.
+
+#### `entryPoint` write vs read
+
+```ts
+// Persist routing for the next offline run (dialog.params.entry_point)
+platform.dialog.entryPoint = 'on_recall';
+
+// Snapshot for this run — use with getScriptPhase(context)
+logger.log('branch', { entryPoint: context.entryPoint });
+```
+
+`ScheduleCallOptions.entryPoint` on `platform.call()` is stored on the **call** row at schedule time — different from assigning `platform.dialog.entryPoint` mid-script.
+
+#### Example
+
 ```ts
 platform.dialog.entryPoint = 'on_recall';
 platform.dialog.result = 'done';
 ```
 
-Setters update the local value immediately and persist to the platform asynchronously. They are not awaitable and should not be used as transactional writes.
+Setters update the local value immediately and persist asynchronously. They are not awaitable and should not be used as transactional writes. See [examples/after-call-continuation.ts](./examples/after-call-continuation.ts).
 
 ### Platform-Scheduled Calls
 
@@ -956,23 +1136,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 +1147,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 means the platform may retry up to three times, waiting about five minutes between 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.)
 
-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
+**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.');
+  }
+});
+```
+
+See [examples/recall-routing-by-attempt.ts](./examples/recall-routing-by-attempt.ts).
+
+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 +1249,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 +1264,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 +1384,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 +1421,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).
+`context.entryPoint` is the routing branch **snapshot** for this run (from `dialog.params.entry_point` at start). To persist a new value, assign `platform.dialog.entryPoint` — see [Dialog State](#dialog-state).
 
 ```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,14 +1480,16 @@ 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`: routing entry point **snapshot** at script start (see [Script Lifecycle](#script-lifecycle-getscriptphase)); persist changes via `platform.dialog.entryPoint`.
+- `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.
 - `context.runTime`: async execution budget helper.
 - `context.env$`: persisted dialog environment as an RxJS `BehaviorSubject`.
 
+Dialog lifecycle status (`dialog.result`) is **not** on `context` — use `platform.dialog.result` ([Dialog State](#dialog-state)).
+
 Use `env$` for persisted script state:
 
 ```ts
@@ -1278,11 +1525,15 @@ WS channels behave like active media channels:
 Headless channels are for offline, queue, or messaging sessions:
 
 - Audio methods are no-ops that log warnings.
-- SIP methods are mostly no-ops.
-- `createAsr()` returns an inert handle.
+- SIP methods are no-ops, except `makeCall()` and `bridge()`, which throw: there is no real leg to
+  create, and a silent no-op would hide the mistake.
+- `createAsr()` returns an inert handle whose observables complete immediately.
 - 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"}