@voctiv/agent-sdk 0.2.12 → 0.2.14

package/README.md

@@ -173,6 +173,70 @@ On SIP channels, `channel.audio.say()` and `channel.audio.play()` automatically
 
 If the call terminates before media becomes available, deferred audio resolves as a no-op.
 
+### SIP Signalling Metadata
+
+On **SIP channels**, `channel.sip` exposes raw signalling beyond call state — useful for
+carrier routing, diversion chains, and vendor SDP attributes.
+
+#### 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`, …).
+
+| Property | Updates during call? |
+| --- | --- |
+| `inviteSipHeaders` | **No** — INVITE snapshot only; outbound B-legs usually `undefined` |
+
+```ts
+const h = channel.sip.inviteSipHeaders;
+const diversion = h?.Diversion; // string | string[] when multiple hops
+const trunkId = h?.['X-Trunk-Id'];
+```
+
+Header names match what the host stack exposes (case-sensitive). Duplicate headers become
+`string[]`.
+
+#### Remote SDP (`remoteSdp`, `getRemoteSdpDetails()`)
+
+| Property / method | Updates during call? |
+| --- | --- |
+| `remoteSdp` | **Yes** — latest negotiated remote SDP (INVITE, 183, 200, re-INVITE) |
+| `getRemoteSdpDetails()` | **Yes** — re-parses current `remoteSdp` on each call |
+
+```ts
+const raw = channel.sip.remoteSdp;
+const details = channel.sip.getRemoteSdpDetails();
+
+details?.session.connection; // e.g. "IN IP4 203.0.113.5"
+details?.attributes.rtpmap; // e.g. "0 PCMU/8000"
+details?.attributes['x-vendor-tag']; // custom a=x-vendor-tag:...
+```
+
+`getRemoteSdpDetails()` parses session lines (`o=`, `s=`, `c=`, `m=audio`) and all `a=`
+attributes. It is not a full SDP validator — use `remoteSdp` when you need the raw body.
+
+#### SIP INFO (`sipInfo$`)
+
+Live stream of incoming SIP INFO messages (`contentType` + `body`). Prefer `dtmf$` for DTMF.
+
+```ts
+channel.sip.sipInfo$.subscribe(({ contentType, body }) => {
+  logger.log('SIP INFO', { contentType, body });
+});
+```
+
+Events before subscribe are not replayed.
+
+#### Relating streams to SDP
+
+| Stream | `sdp` field |
+| --- | --- |
+| `progress$` | Present when a 1xx response carries SDP (e.g. 183 early media) |
+| `sipSignal$` | Present only on callbacks that include SDP; often empty on final `active` |
+
+For the **persisted** negotiated SDP, use `remoteSdp` / `getRemoteSdpDetails()`, not only
+the per-event `sdp` on `sipSignal$`.
+
 ### SIP Controls
 
 `channel.sip` also supports:
@@ -202,8 +266,11 @@ 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$` | Raw SIP INFO messages (`SipInfo`) |
-| `sipSignal$` | Low-level SIP stack events (`SipSignal`) |
+| `sipInfo$` | Live incoming SIP INFO (`SipInfo`: `contentType`, `body`) |
+| `sipSignal$` | Low-level SIP stack events (`SipSignal`; `sdp` only on that callback) |
+| `remoteSdp` | Latest negotiated remote SDP body; updates when new SDP arrives |
+| `inviteSipHeaders` | Inbound INVITE header snapshot (`SipInviteHeaders`); does not update |
+| `getRemoteSdpDetails()` | Parse `remoteSdp` → `ParsedSdpDetails` (session + `a=` attributes) |
 | `sendProgress()` | Inbound: send 183 Session Progress → `early` |
 | `waitForEarly()` | Await `early` or `active` (Promise) |
 | `waitForAnswer()` | Await final 200 OK (Promise) |
@@ -216,7 +283,10 @@ SIP-only unless noted. WS/headless: most methods are no-ops; `state` behaves as
 | `makeCall(opts)` | Outbound B-leg (`MediaChannel`); `sipUri` or `msisdn` |
 | `bridge(other)` | Cross-connect two SIP calls; returns teardown `() => void` |
 
-Prefer `dtmf$` over `sipInfo$` for DTMF. Prefer `state$` / `early$` / `answered$` over raw `sipSignal$` unless you need low-level SIP details.
+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.
 
 ### SIP Bridge
 
@@ -926,6 +996,11 @@ await platform.call('+12025551234', {
 
 This means the platform may retry up to three times, waiting about five minutes between attempts.
 
+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
+(`context.agent?.recallCount` / `context.agent?.recallDelay`, legacy `nn.get_recall_count()` /
+`nn.get_recall_delay()`).
+
 Other scheduling options:
 
 - `priority`: higher-priority calls can be processed earlier by the dialer.
@@ -1085,9 +1160,9 @@ export default defineScript(async ({ channel, context, platform }) => {
 
 `context` includes identity, telephony fields, params, routing metadata, and runtime helpers.
 
-### Agent env and storage
+### Agent env, recall defaults, and storage
 
-When the host exposes agent identity, `context.agent` provides agent-scoped global variables:
+When the host exposes agent identity, `context.agent` provides agent-scoped helpers:
 
 ```ts
 // Read all agent env keys
@@ -1100,6 +1175,42 @@ const counter = await context.agent?.env?.<number>('visitCount');
 await context.agent?.env?.('visitCount', 42, { expire: 30 });
 ```
 
+#### Recall settings (agent defaults vs effective)
+
+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 |
+
+Precedence for effective values: **dialog/call params** (`recall_count`, `recall_delay`) **>** agent CMS defaults.
+
+`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, {
+  recallCount: context.recallCount,
+  recallDelay: context.recallDelay,
+  entryPoint: 'on_follow_up',
+});
+
+// Log CMS defaults vs per-dialog override
+logger.log('recall config', {
+  effective: { count: context.recallCount, delay: context.recallDelay },
+  agentDefault: {
+    count: context.agent?.recallCount,
+    delay: context.agent?.recallDelay,
+  },
+  attempt: context.attempt,
+});
+```
+
+Values are loaded once at script start from the legacy agent row (cached with other LE agent
+resolution). They are plain snapshots — not `BehaviorSubject`s and not re-fetched during the run.
+
 `context.storage('key1', 'key2')` reads CMS/global variables from agent settings, then company-level
 fallback. Always returns an object with every requested key (value or `null`).
 
@@ -1125,6 +1236,9 @@ Important fields:
 - `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.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`.

package/dist/index.d.ts

@@ -19,6 +19,13 @@
  *
  * Platform APIs (`platform.nlu`, `platform.call`, messaging, dialog writes, phrase records)
  * are available when the host enables platform integration.
+ *
+ * ### SIP metadata on live calls
+ *
+ * On SIP channels, {@link import('./types/sip').ChannelSip} exposes INVITE header snapshots
+ * ({@link import('./types/sip').SipInviteHeaders}), negotiated {@link import('./types/sip').ChannelSip.remoteSdp},
+ * parsed SDP attributes ({@link import('./types/sip').ParsedSdpDetails} via `getRemoteSdpDetails()`),
+ * and live SIP INFO ({@link import('./types/events').SipInfo} on `sipInfo$`). See **`README.md`** → SIP Signalling Metadata.
  */
 export { defineScript } from './define-script';
 export type { ScriptContext, ScriptFn } from './define-script';
@@ -28,7 +35,7 @@ export type { NluScriptApi, PlatformApi, DialogApi, ScheduleCallOptions, SendMes
 export type { ScriptLogger } 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, } from './types/sip';
+export type { ChannelSip, SipState, SipProgressEvent, SipInviteHeaders, ParsedSdpDetails, } from './types/sip';
 export type { MediaError } from './types/errors';
 export type { AsrHandle, AsrConfig, AsrVadConfig, AsrSmartTurnConfig } from './types/asr-handle';
 export type { MixerQueueControl, PlayOptions, PresayOptions, PreloadOptions, TtsStrategy, TtsVendor } from './types/mixer';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -20,6 +20,13 @@
  *
  * Platform APIs (`platform.nlu`, `platform.call`, messaging, dialog writes, phrase records)
  * are available when the host enables platform integration.
+ *
+ * ### SIP metadata on live calls
+ *
+ * On SIP channels, {@link import('./types/sip').ChannelSip} exposes INVITE header snapshots
+ * ({@link import('./types/sip').SipInviteHeaders}), negotiated {@link import('./types/sip').ChannelSip.remoteSdp},
+ * parsed SDP attributes ({@link import('./types/sip').ParsedSdpDetails} via `getRemoteSdpDetails()`),
+ * 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;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAEH,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AAerB,yDAAwD;AAA/C,gHAAA,cAAc,OAAA;AA0CvB,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;AA4CvB,uDAG+B;AAF7B,2HAAA,0BAA0B,OAAA;AAC1B,qHAAA,oBAAoB,OAAA"}

package/dist/types/events.d.ts

@@ -5,22 +5,27 @@ export interface DtmfEvent {
     /** Duration of the tone in milliseconds, normalized by the channel when available. */
     duration: number;
 }
-/** Incoming SIP INFO message. */
+/** Incoming SIP INFO message on a live SIP call leg. */
 export interface SipInfo {
-    /** MIME content type (e.g. `"application/dtmf-relay"`). May be empty for low-level Sofia events. */
+    /** MIME content type (e.g. `"application/dtmf-relay"`, `"application/xml"`). */
     contentType: string;
-    /** Message body. May be empty for low-level Sofia events. */
+    /** Raw message body as received from the stack. */
     body: string;
 }
-/** SIP call state change signal. */
+/** Low-level Sofia SIP stack state-change event (see also {@link import('./sip').SipState}). */
 export interface SipSignal {
-    /** Raw telephony/Sofia call state, not normalized to SDK `SipState`. */
+    /** Raw telephony/Sofia call state string (not normalized to SDK {@link import('./sip').SipState}). */
     state: string;
-    /** SIP response status code (e.g. `200`, `486`). */
+    /** SIP response status code when present (e.g. `180`, `183`, `200`, `486`). */
     statusCode?: number;
-    /** SIP response reason phrase. */
+    /** SIP response reason phrase when present. */
     statusPhrase?: string;
-    /** SDP body (for media negotiation events). */
+    /**
+     * SDP body attached to **this** state callback only.
+     *
+     * Often empty on `active` (200 OK) when SDP was already received on an earlier 183/INVITE.
+     * Use {@link import('./sip').ChannelSip.remoteSdp} for the persisted negotiated SDP.
+     */
     sdp?: string;
 }
 /** Arbitrary data message used for WS data-channel communication between script and client. */

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

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,MAAM,WAAW,SAAS;IACxB,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,iCAAiC;AACjC,MAAM,WAAW,OAAO;IACtB,oGAAoG;IACpG,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,oCAAoC;AACpC,MAAM,WAAW,SAAS;IACxB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,+FAA+F;AAC/F,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAC;CAClB"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,MAAM,WAAW,SAAS;IACxB,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wDAAwD;AACxD,MAAM,WAAW,OAAO;IACtB,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gGAAgG;AAChG,MAAM,WAAW,SAAS;IACxB,sGAAsG;IACtG,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,+FAA+F;AAC/F,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAC;CAClB"}

package/dist/types/nlu.d.ts

@@ -2,32 +2,67 @@
  * Options for `platform.nlu.extract()`.
  *
  * Compatible with logic-executor `NeuroNluRecognitionRequest`. ScriptEngine forwards
- * `entities`, `intents`, `context`,
- * `use_neuro_api`, and `use_synonyms` to NLU v3 `/infer`. Exclude fields are
- * kept in the SDK for source compatibility with older scripts, but are not
- * part of the default ScriptEngine request payload.
+ * all fields to nlu-engine `/nlu_engine`. Exclude fields (`entities_exclude`,
+ * `intents_exclude`) are mapped to `entities_policy` / `intents_policy`.
  */
 export interface NluExtractOptions {
-    /** Include only these entity types (e.g. `"date"`, `"phone"`); forwarded as `entities`. */
+    /**
+     * Entity names to search — always forwarded to nlu-engine as a JSON array.
+     * Prefer `['confirmation', 'check']`; comma-separated string is accepted for LE compat.
+     */
     entities?: string | string[] | null;
-    /** Legacy compatibility field; not part of the default ScriptEngine request payload. */
+    /** Legacy compatibility field; mapped to exclude policy on nlu-engine. */
     entities_exclude?: string | string[] | null;
-    /** Include only these intent names; forwarded as `intents`. */
+    /**
+     * Intent names to search — always forwarded to nlu-engine as a JSON array.
+     * Prefer `['balance_check']`; comma-separated string is accepted for LE compat.
+     */
     intents?: string | string[] | null;
-    /** Legacy compatibility field; not part of the default ScriptEngine request payload. */
+    /** Legacy compatibility field; mapped to exclude policy on nlu-engine. */
     intents_exclude?: string | string[] | null;
     /**
      * Additional context for disambiguation.
      *
-     * Objects and arrays are JSON-stringified before sending. If omitted, the runtime
-     * serializes current dialog params and uses that as NLU context.
+     * Objects and arrays are JSON-stringified before sending. When omitted, the runtime
+     * uses dialog `flag` (logic-executor scripts usually pass the same value explicitly).
      */
     context?: string | unknown[] | Record<string, unknown> | null;
-    /** Forwarded as `use_neuro_api`; backend-specific flag for the NLU service. */
+    /**
+     * BCP-47 / LE language for this call only (e.g. `es-ES`).
+     * Default NLU language comes from the LE agent (`_nlu.language`), not `context.lang`.
+     */
+    language?: string;
+    /** Alias for {@link language}. */
+    lang?: string;
+    /** Forwarded as `use_neuro_api`; nlu-engine may call remote NLU API when true. */
     use_neuro_api?: boolean;
-    /** Forwarded as `use_synonyms`; enables synonym expansion in the NLU service. */
+    /** Forwarded as `use_synonyms`; enables synonym expansion in nlu-engine. */
     use_synonyms?: boolean;
 }
-/** Raw parsed JSON response from NLU v3 `/infer` endpoint. */
-export type NluInferResult = Record<string, unknown>;
+export interface NluProbabilityValue {
+    value: unknown;
+    probability: number;
+}
+/**
+ * logic-executor `NeuroNluRecognitionResult` method surface returned from
+ * `platform.nlu.extract()` / `extract$()`.
+ */
+export interface NluInferResult {
+    utterance(): string | null;
+    context(): unknown;
+    entity(entityName: string): unknown;
+    intent(intentName: string): unknown;
+    has_entity(entityName: string): boolean;
+    has_intent(intentName: string): boolean;
+    has_entities(): boolean;
+    has_intents(): boolean;
+    entities(): Record<string, unknown>;
+    intents(): Record<string, unknown>;
+    entity_with_probability(entityName: string): NluProbabilityValue | null;
+    intent_with_probability(intentName: string): NluProbabilityValue | null;
+    entities_with_probability(): Record<string, NluProbabilityValue>;
+    intents_with_probability(): Record<string, NluProbabilityValue>;
+    dump(): Record<string, unknown>;
+    dump_json(): string;
+}
 //# sourceMappingURL=nlu.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"nlu.d.ts","sourceRoot":"","sources":["../../src/types/nlu.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACpC,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAC5C,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACnC,wFAAwF;IACxF,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9D,+EAA+E;IAC/E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iFAAiF;IACjF,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,8DAA8D;AAC9D,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC"}
+{"version":3,"file":"nlu.d.ts","sourceRoot":"","sources":["../../src/types/nlu.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACpC,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAC5C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACnC,0EAA0E;IAC1E,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9D;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,IAAI,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,IAAI,OAAO,CAAC;IACnB,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,YAAY,IAAI,OAAO,CAAC;IACxB,WAAW,IAAI,OAAO,CAAC;IACvB,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAAC;IACxE,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAAC;IACxE,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACjE,wBAAwB,IAAI,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAChE,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,SAAS,IAAI,MAAM,CAAC;CACrB"}

package/dist/types/platform.d.ts

@@ -4,9 +4,11 @@ import type { LegacyGetRecordsParams, LegacyPhraseRecord } from './legacy-phrase
 /**
  * NLU (Natural Language Understanding) API.
  *
- * Provides intent/entity extraction through the legacy NLU v3 `/infer` endpoint.
+ * Provides intent/entity extraction through the pool-local nlu-engine
+ * (`POST /nlu_engine?agent_id=…`), same path as logic-executor
+ * `NeuroNluClient.recognize_with_proxy`.
  * ScriptEngine allows this API when `context.legacyV3Compat` is `true` and NLU
- * runtime settings are configured (`NLU_V3_BASE_URL` plus a resolved numeric
+ * runtime settings are configured (`NLU_ENGINE_BASE_URL` plus a resolved numeric
  * agent id). Calls fail fast with a descriptive error otherwise.
  *
  * Compatible with logic-executor `nn.extract()` request/response shape.
@@ -15,14 +17,14 @@ export interface NluScriptApi {
     /**
      * Extract intents and entities from one user utterance.
      *
-     * The runtime sends `{ phrase, context, agent_id }` to NLU v3. If
-     * `options.context` is omitted, it serializes the current dialog params
-     * (`context.dialogParams`, then legacy fallbacks) as the request context.
+     * The runtime sends a logic-executor-compatible recognition request to
+     * nlu-engine (`/nlu_engine?agent_id=…`). Pass `options.context` explicitly when
+     * needed (same as LE `nlu.extract(..., context=flag)`).
      *
      * @param utterance - User input text to analyze.
      * @param options - Optional NLU filters and flags. `entities`, `intents`,
-     *   `use_neuro_api`, and `use_synonyms` are forwarded by ScriptEngine.
-     * @returns Raw parsed JSON response from the NLU `/infer` endpoint.
+     *   `language` / `lang`, `use_neuro_api`, and `use_synonyms` are forwarded by ScriptEngine.
+     * @returns logic-executor-compatible {@link NluInferResult} (`entity()`, `has_entities()`, …).
      */
     extract(utterance: string, options?: NluExtractOptions): Promise<NluInferResult>;
     /**
@@ -58,9 +60,15 @@ export interface ScheduleCallOptions {
      * Forwarded to the dialer for `X-Via-Trunk` / gateway routing.
      */
     channel?: string | number;
-    /** How many times to retry on failure. Stored as `recall_count` in call params. */
+    /**
+     * 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}.
+     */
     recallCount?: number;
-    /** Delay in seconds between retries. Stored as `recall_delay` in call params. */
+    /**
+     * Delay in seconds between retries. Stored as `recall_delay` in call params.
+     * When omitted, the host defaults from {@link import('./script-context').ScriptDialogContext.recallDelay}.
+     */
     recallDelay?: number;
     /** Entry point to use after a successful call. Stored as `on_success_call`. */
     onSuccessCall?: string;
@@ -174,7 +182,8 @@ export interface PlatformApi {
     /**
      * Voctiv platform only: load `record_phrase` / `record_phrase_file` rows from the LE PostgreSQL database
      * (same filters as old `RecordPhrase.get_records`). Returns playable phrase record objects.
-     * Requires numeric `agent_id` on the dialog (params or `NLU_DEFAULT_AGENT_ID`) and
+     * Requires a resolved numeric LE `agent.id` (dialog / leAgentId / Omni nlu.agentId).
+     * Optional dev fallback: `NLU_DEFAULT_AGENT_ID`.
      * `LEGACY_V3_RECORD_PHRASE_ROOT` pointing at the phrase file storage root.
      */
     getRecords?(params: LegacyGetRecordsParams): Promise<LegacyPhraseRecord[]>;

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

@@ -5,7 +5,7 @@ export interface AgentEnvSetOptions {
     /** TTL in days, matching legacy `nn.agent.env(..., expire=days)`. */
     expire?: number;
 }
-/** Legacy LE-style global environment shared by all dialogs of the agent. */
+/** Legacy LE-style agent profile and global env shared by all dialogs of the agent. */
 export interface AgentContext {
     /** Numeric NLU / LE agent id, when resolved by the host. */
     id?: number;
@@ -18,6 +18,22 @@ export interface AgentContext {
         (key: string, value: unknown, options?: AgentEnvSetOptions): Promise<void>;
         (values: Record<string, unknown>, options?: AgentEnvSetOptions): Promise<void>;
     };
+    /**
+     * CMS / LE contact-rules default: `agent.recall_count`.
+     *
+     * Snapshot at script start (immutable for this session). Legacy parity: `nn.get_recall_count()`.
+     * For the value that applies to the **current** dialog/call (including per-dialog overrides),
+     * use top-level {@link ScriptDialogContext.recallCount}.
+     */
+    recallCount?: number;
+    /**
+     * CMS / LE contact-rules default: `agent.delay`, converted to **seconds**.
+     *
+     * Snapshot at script start (immutable for this session). Legacy parity: `nn.get_recall_delay()`
+     * (LE returns a time string; the host normalizes to seconds here).
+     * For the effective delay on this dialog/call, use top-level {@link ScriptDialogContext.recallDelay}.
+     */
+    recallDelay?: number;
 }
 /** Read LE/CMS global variables from `storage` with agent → company fallback. */
 export type StorageContextApi = (...keys: string[]) => Promise<Record<string, string | null>>;
@@ -52,13 +68,19 @@ export interface ScriptDialogContext {
     /**
      * Numeric NLU agent id used for `platform.nlu.extract()` and legacy DB operations.
      *
-     * Resolved by the server from Omni/LE mapping or env (`NLU_DEFAULT_AGENT_ID` /
-     * `AGENT_ID`). Client/session params named `agent_id`, `agentId`, `agentUuid`,
+     * Resolved by the server from LE dialog/call, Omni `nlu.agentId`, or optional env
+     * (`NLU_DEFAULT_AGENT_ID` / `AGENT_ID`). Client/session params named `agent_id`, `agentId`, `agentUuid`,
      * and `agent_uuid` are stripped before context construction and cannot spoof it.
      * May be `0` when no agent id is configured; NLU and `platform.call()` will then fail.
      */
     agentId: number;
-    /** Agent identity and legacy global agent env (`context.agent.env`). */
+    /**
+     * Agent identity, CMS recall defaults, and legacy global agent env (`context.agent.env`).
+     *
+     * {@link AgentContext.recallCount} / {@link AgentContext.recallDelay} are agent-wide settings
+     * from CMS. Top-level {@link ScriptDialogContext.recallCount} / {@link ScriptDialogContext.recallDelay}
+     * are the **effective** values for this run (dialog/call params override agent defaults).
+     */
     agent?: AgentContext;
     /**
      * Read global variables configured in agent settings, then company-level globals.
@@ -125,11 +147,24 @@ export interface ScriptDialogContext {
     availableMediaKeys?: string[];
     /** Script entry point for routing (e.g. `"on_recall"`, `"on_message_api_received"`). */
     entryPoint?: string;
-    /** Current recall attempt number (starts at 0). */
+    /** Current recall attempt number for this dialog (from `dialog.params.attempt`, starts at 0). */
     attempt?: number;
-    /** Max recall attempts configured for this dialog. */
+    /**
+     * Effective max recall attempts for **this** dialog/call.
+     *
+     * 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.
+     */
     recallCount?: number;
-    /** Delay in seconds between recall attempts. */
+    /**
+     * Effective delay in **seconds** between recall attempts for **this** dialog/call.
+     *
+     * 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.
+     */
     recallDelay?: number;
     /**
      * Inbound message that triggered this headless session.

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":";;AA8NA,wCAaC;AAnCD,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;QAAE,OAAO,WAAW,CAAC;IAEnF,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":";;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"}

package/dist/types/sip.d.ts

@@ -132,6 +132,49 @@ export interface SipProgressEvent {
  * `waitForAnswer()` await points are useful when you need to **sequence logic** around
  * call state (e.g. create ASR only after media is available).
  */
+/**
+ * SIP headers captured from an **inbound INVITE** at call setup.
+ *
+ * Keys use the on-wire header name (`Diversion`, `P-Asserted-Identity`, `X-Trunk-Id`, …).
+ * Values are a single string or a string array when the same header appears multiple times
+ * (e.g. several `Diversion` hops).
+ *
+ * **Snapshot only** — does not update on 180/200, re-INVITE, or BYE. Outbound B-legs
+ * typically have no INVITE snapshot (`undefined`). For carrier-specific extension headers,
+ * prefer exact key names from your SBC; casing matches what Sofia exposes.
+ */
+export type SipInviteHeaders = Record<string, string | string[]>;
+/**
+ * Structured parse of {@link ChannelSip.remoteSdp}.
+ *
+ * Parses selected session lines (`o=`, `s=`, `c=`, `m=audio`) and all `a=` attribute lines.
+ * Attribute keys are the part **before** the first colon in `a=name:value` (e.g. `rtpmap`,
+ * `fmtp`, vendor `x-custom`). Flag attributes without a colon (e.g. `sendrecv`) map to `""`.
+ * Duplicate attribute names become `string[]`.
+ *
+ * @example
+ * ```ts
+ * const d = channel.sip.getRemoteSdpDetails();
+ * d?.session.connection; // "IN IP4 203.0.113.5"
+ * d?.attributes.rtpmap; // "0 PCMU/8000"
+ * d?.attributes['x-vendor-id']; // custom a=x-vendor-id:abc
+ * ```
+ */
+export interface ParsedSdpDetails {
+    /** Selected SDP session description lines (not a full SDP grammar parse). */
+    session: {
+        /** `o=` origin line (without prefix). */
+        origin?: string;
+        /** `s=` session name. */
+        sessionName?: string;
+        /** Last `c=` connection line seen (session or media level). */
+        connection?: string;
+        /** `m=audio` media line (without prefix). */
+        mediaAudio?: string;
+    };
+    /** SDP `a=` attributes keyed by attribute name. */
+    attributes: Record<string, string | string[]>;
+}
 export interface ChannelSip {
     /**
      * Emits every time the remote party sends a DTMF digit (RFC 2833 in-band or SIP INFO).
@@ -144,20 +187,51 @@ export interface ChannelSip {
      */
     readonly dtmf$: Observable<DtmfEvent>;
     /**
-     * Raw SIP INFO messages received on this call leg.
+     * Emits each incoming SIP INFO on this call leg (`contentType` + `body`).
+     *
+     * Useful for carrier-specific signalling (e.g. `application/dtmf-relay`, XML payloads).
+     * **Hot stream** — events before subscribe are not replayed. Prefer {@link dtmf$} for DTMF.
      *
-     * Useful for carrier-specific signalling (e.g. `application/dtmf-relay`). On the
-     * current SIP runtime this stream is low-level and may not include parsed body
-     * details for every Sofia event; prefer `dtmf$` for DTMF.
+     * ```ts
+     * sip.sipInfo$.subscribe(({ contentType, body }) => {
+     *   logger.log('SIP INFO', { contentType, body });
+     * });
+     * ```
      */
     readonly sipInfo$: Observable<SipInfo>;
     /**
      * Low-level SIP state-change events from the underlying Sofia stack.
      *
      * Prefer the higher-level **`state$`**, **`progress$`**, **`early$`**, **`answered$`**
-     * observables unless you need raw Sofia event details.
+     * observables unless you need raw Sofia event details. The `sdp` field is present
+     * only when that specific state callback carries an SDP body.
      */
     readonly sipSignal$: Observable<SipSignal>;
+    /**
+     * Latest negotiated **remote party SDP** body (raw text).
+     *
+     * **Inbound:** usually present from INVITE. **Outbound:** often empty until 183/200
+     * with SDP; may change on re-INVITE. Synchronous getter — re-read after
+     * {@link progress$} / {@link sipSignal$} events that carry `sdp`. Undefined on WS/headless.
+     */
+    readonly remoteSdp?: string;
+    /**
+     * Snapshot of SIP headers from the **inbound INVITE** — see {@link SipInviteHeaders}.
+     *
+     * ```ts
+     * const h = channel.sip.inviteSipHeaders;
+     * const diversion = h?.Diversion; // string | string[] | undefined
+     * const trunk = h?.['X-Trunk-Id'];
+     * ```
+     */
+    readonly inviteSipHeaders?: SipInviteHeaders;
+    /**
+     * Parse the current {@link remoteSdp} into {@link ParsedSdpDetails}.
+     *
+     * Returns `null` when no remote SDP is available yet. Re-parses on every call from the
+     * latest `remoteSdp` value (no separate cache in the host channel).
+     */
+    getRemoteSdpDetails(): ParsedSdpDetails | null;
     /**
      * Live observable of the current call state.
      *

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voctiv/agent-sdk",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "Voctiv TypeScript agent SDK: defineScript and platform types for the voice/dialog scripting runtime.",
   "license": "UNLICENSED",
   "author": "",