@voctiv/agent-sdk 0.3.2 → 0.3.3

package/README.md

@@ -70,7 +70,15 @@ export default defineScript(async ({ channel, logger, context }) => {
 });
 ```
 
+This snippet assumes a **live answered** channel: inbound after you `answer()`, or a campaign
+outbound that started on `'on_answer'` (the default). It is not how you pick up ringing, 1xx, or
+a 4xx. Those are two different outbound stories:
 
+- **Campaign / `platform.call`** — `defineScript(fn, { outboundCallMode })` decides *when* the
+  host starts this session. See [Campaign Outbound And `outboundCallMode`](#campaign-outbound-and-outboundcallmode).
+- **A second leg from an already-running script** — `channel.sip.makeCall()`, then
+  `waitForEarly()` / `waitForAnswer()` on the **returned** channel. See
+  [B-leg outbound (already in session)](#b-leg-outbound-already-in-session).
 
 ## Examples
 
@@ -79,6 +87,9 @@ The `[examples/](./examples/)` folder contains copy-paste-ready scripts:
 
 | Example                                                                     | Description                                                                |
 | --------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| [outbound-on-answer.ts](./examples/outbound-on-answer.ts)                   | Campaign outbound on `200 OK` (`outboundCallMode: 'on_answer'`, the default) |
+| [outbound-from-invite.ts](./examples/outbound-from-invite.ts)               | Campaign outbound from INVITE (`outboundCallMode: 'from_invite'`)          |
+| [outbound-script-dial.ts](./examples/outbound-script-dial.ts)               | Script dials the campaign leg (`outboundCallMode: 'script_dial'`)          |
 | [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`    |
@@ -130,6 +141,11 @@ const maxAttempts = parseRecallCount(context.dialogParams?.recall_count);
 Ship it in a **sibling** module (`media-providers/`), not in the sandboxed script entry — see
 [Custom ASR / TTS Providers](#custom-asr--tts-providers).
 
+`defineScript(fn, options)` additionally declares `ScriptCallOptions`, whose `outboundCallMode`
+(`OutboundCallMode`: `'on_answer'` | `'from_invite'` | `'script_dial'`) the host reads
+**before** the script runs to decide when the session starts — see
+[Campaign Outbound And `outboundCallMode`](#campaign-outbound-and-outboundcallmode).
+
 **Three different “context” names:**
 
 
@@ -172,6 +188,11 @@ The important states are:
 - `active`: final 200 OK has been received or sent.
 - `terminated`: the call ended and no more audio is possible.
 
+`channel.sip.state === 'early'` is **media** (RTP before `200 OK`). It is not
+`getScriptPhase(context) === 'early'`. That phase is a snapshot of *when the live session started*
+(campaign `'from_invite'` or inbound pre-answer) and **does not flip** when the call answers — use
+`channel.sip.isAnswered` / `answered$` for the live state.
+
 
 
 ### How Pre-Answer Works
@@ -196,9 +217,20 @@ For outbound calls, pre-answer is controlled by the remote side. If the remote e
 
 `early` is a media-ready state, not a final answer state. `answer()` is still the explicit transition that sends final `200 OK` for inbound calls. External billing behavior depends on the carrier.
 
-### Outbound Pre-Answer
+### Two outbound stories
+
+Do not mix these up. Both can see 183 / early media, but they start in different places.
+
+| You want… | Use | Conversation on |
+| --------- | --- | --------------- |
+| The **campaign** (or `platform.call`) to start this script at 200 OK, at INVITE, or with no leg yet | `defineScript(fn, { outboundCallMode })` — [below](#campaign-outbound-and-outboundcallmode) | `channel`, except `'script_dial'` which talks on the **returned** `leg` |
+| A **second** outbound from a script that is already running (transfer target, IVR, operator) | `channel.sip.makeCall()` — next subsection | the **returned** B-leg |
+
+`outboundCallMode` never changes inbound or a B-leg you opened yourself.
+
+### B-leg outbound (already in session)
 
-For outbound calls, early media starts when the remote side sends a provisional response with SDP, usually `183 Session Progress`. This is useful for IVRs that speak before answering.
+Early media on a B-leg starts when the remote side sends a provisional response with SDP, usually `183 Session Progress`. This is useful for IVRs that speak before answering. The parent script is already live; `outboundCallMode` does not apply here.
 
 ```ts
 const bLeg = await channel.sip.makeCall({
@@ -217,6 +249,175 @@ asr.result$.subscribe((text) => {
 
 `waitForEarly()` resolves when the call reaches either `early` or `active`. If a carrier skips early media and answers directly, it resolves on the final answer.
 
+### Campaign Outbound And `outboundCallMode`
+
+This is **when the platform starts the script** for a campaign / `platform.call` row — not how you
+open a B-leg from inside a live session ([that is `makeCall`](#b-leg-outbound-already-in-session)).
+
+`OutboundCallMode` (`'on_answer'` | `'from_invite'` | `'script_dial'`) is the second argument of
+`defineScript`. The host reads it **before** the session starts, because it decides *when* (and
+whether) the platform dials. The names describe that moment.
+
+```ts
+import { defineScript } from '@voctiv/agent-sdk';
+
+defineScript(async () => undefined); // same as 'on_answer'
+defineScript(async () => undefined, { outboundCallMode: 'on_answer' });
+defineScript(async () => undefined, { outboundCallMode: 'from_invite' });
+defineScript(async () => undefined, { outboundCallMode: 'script_dial' });
+```
+
+A script that passes nothing stays on `'on_answer'` — the Basic Script above is that path.
+Inbound legs and `channel.sip.makeCall()` B-legs are unchanged: they already hand the script a
+channel before the final answer.
+
+`answer_date` and billing never move: both come from the `200 OK`, never from `183`.
+`getScriptPhase` is a snapshot of how the run **started** and does not flip when the answer arrives
+— use `channel.sip.isAnswered` or `answered$` for the live state. (`defineScript` stores the
+options on the function as `callOptions` — type `ScriptFnWithCallOptions` — and the host copies
+that into `context.startedBeforeAnswer` / `context.startedWithoutLeg`.)
+
+
+| `outboundCallMode`      | Who dials               | Script starts on                    | `getScriptPhase` at start                              | Conversation channel   |
+| ----------------------- | ----------------------- | ----------------------------------- | ------------------------------------------------------ | ---------------------- |
+| `'on_answer'` (default) | host                    | the `200 OK`                        | `'online'`                                             | `channel`              |
+| `'from_invite'`         | host (after script up)  | INVITE — session is already running | `'early'` (stays `'early'` after answer)               | `channel`              |
+| `'script_dial'`         | script (`sip.makeCall`) | nothing — no leg exists yet         | `'dialing'` (stays `'dialing'` after the script dials) | the **returned** `leg` |
+
+Copy-paste: [outbound-on-answer.ts](./examples/outbound-on-answer.ts),
+[outbound-from-invite.ts](./examples/outbound-from-invite.ts),
+[outbound-script-dial.ts](./examples/outbound-script-dial.ts).
+
+#### `'on_answer'` — start on answer (default)
+
+The host sends the INVITE and **holds the script** until the remote party answers (`200 OK`). Busy,
+no-answer, reject, or the dialer timeout never reach the live handler: the campaign writes
+`call.result` and may run `after_call_failed` / recall instead.
+
+Use this when the script is a conversation: greeting, turn watchdog, max-duration timer. They all
+assume a human is already on the line. Existing agents that do not pass options keep this behavior.
+
+```ts
+import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+
+export default defineScript(async ({ channel, context }) => {
+  // Live outbound: always 'online'. Headless before_call / after_call_* still apply.
+  if (getScriptPhase(context) !== 'online') return;
+
+  await channel.audio.say('Hello!');
+  const asr = await channel.createAsr();
+});
+```
+
+How to work with it:
+
+- Talk on `channel` — audio, ASR, SIP waiters are already live and answered.
+- Do **not** wait for `183` / `progress$`: the script was not running then.
+- Do **not** call `channel.sip.makeCall()` for the campaign number; the host already dialed it.
+- Inbound is unchanged: the same export still sees `'online'` (or `'early'` only if you also opted
+  into `'from_invite'`).
+
+#### `'from_invite'` — script first, host dials
+
+The host starts the script **before** any INVITE, then automatically dials the campaign number on
+the same `channel`. Subscribe first, then wait: 180/183 arrive on `progress$` / `sipSignal$`, and a
+4xx/5xx rejects `waitForAnswer()` with the SIP result in the message (`486 Busy Here`). The
+greeting still belongs after the answer — otherwise it plays into ringback.
+
+```ts
+import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+
+export default defineScript(
+  async ({ channel, logger, context }) => {
+    if (getScriptPhase(context) === 'early') {
+      channel.sip.progress$.subscribe(({ statusCode }) => {
+        logger.log('progress', { statusCode });
+      });
+      try {
+        await channel.sip.waitForAnswer();
+      } catch (err) {
+        logger.warn('outbound failed', { err });
+        return;
+      }
+    }
+
+    await channel.audio.say('Hello!');
+  },
+  { outboundCallMode: 'from_invite' },
+);
+```
+
+How to work with it:
+
+- Talk on `channel` — the host already dialed; do **not** call `makeCall()` for the campaign number.
+- `getScriptPhase` is `'early'` for the whole live run (it does not flip on `200 OK`). Read
+  `channel.sip.isAnswered` / `answered$` for the live state.
+- `audio.say` / `createAsr` wait until the leg has media, then run on this channel.
+- On inbound, `'from_invite'` still reports `'early'` when the session starts before the answer.
+- Unlike `'on_answer'`, a 4xx/5xx **is** visible in this handler — catch `waitForAnswer()` or subscribe
+  to `sipSignal$` / `events.terminated$`.
+
+#### `'script_dial'` — dial the leg yourself
+
+The host does **not** send an INVITE. The script starts with no leg: `sip.state === 'idle'`, no
+audio, phase `'dialing'`. It opens the leg itself and talks on the channel that **comes back** —
+the same shape as a `makeCall()` B-leg. The starting `channel` can only dial.
+
+```ts
+import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+
+export default defineScript(
+  async ({ channel, logger, context }) => {
+    if (getScriptPhase(context) !== 'dialing') return;
+
+    // Empty options: campaign msisdn + the call row's trunk.
+    const leg = await channel.sip.makeCall({});
+
+    leg.sip.progress$.subscribe(({ statusCode }) => {
+      logger.log('progress', { statusCode });
+    });
+    await leg.sip.waitForAnswer();
+
+    await leg.audio.say('Hello!');
+    const asr = await leg.createAsr();
+  },
+  { outboundCallMode: 'script_dial' },
+);
+```
+
+How to work with it:
+
+- **Conversation is on `leg`, not on `channel`.** `channel.audio.say` / `createAsr` before
+  `makeCall` are no-ops with a warning. `channel.sip.waitForAnswer()` rejects — there is no leg.
+- `makeCall({})` dials the campaign number over the row's trunk. Pass `msisdn` (and `channel` for a
+  different trunk) to dial somewhere else, exactly as in a live session.
+- `makeCall` **resolves on media** (183/200) and **rejects** when the leg fails (`486 Busy Here`) or
+  times out. A retry loop is `try` / `catch`, not a race on `terminated$`.
+- The **first** successful `makeCall` is the one the platform reports on: `call.result`,
+  `answer_date`, duration, recording, transcription. Later legs are B-legs. A run that never dials
+  leaves the row with `-ERR Script dialed no call`.
+- The dialer's answer timeout no longer applies to the campaign row. The worker slot is held from
+  the moment the row is claimed until the script returns. Returning hangs up any leg still up.
+- `getScriptPhase` stays `'dialing'` after the script opens a leg. Gate on it to decide *whether*
+  to dial; use `leg.sip.isAnswered` for *whether someone picked up*.
+
+An existing agent that already talks on `ctx.channel` does not need a rewrite: take the returned
+leg once, then keep the rest of the script as-is.
+
+```ts
+import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+
+export default defineScript(
+  async (ctx) => {
+    const phase = getScriptPhase(ctx.context);
+    const channel =
+      phase === 'dialing' ? await ctx.channel.sip.makeCall({}) : ctx.channel;
+    await channel.audio.say('Hello!');
+  },
+  { outboundCallMode: 'script_dial' },
+);
+```
+
 ### Inbound Pre-Answer
 
 For inbound calls, call `channel.sip.sendProgress()` to send `183 Session Progress` with SDP. This enters `early` state and enables full-duplex audio before the final answer.
@@ -867,12 +1068,16 @@ the full surface and IDEs autocomplete correctly:
 | Interface | Role |
 | --- | --- |
 | `ScriptAsrConnector` | Custom STT connector returned by an `asr` factory |
+| `ScriptAsrConnectorError` | Error payload on `ScriptAsrConnector.error$` |
 | `ScriptTtsConnector` | Unified batch + optional streaming TTS connector |
+| `ScriptTtsSynthesisContext` | Synthesis context passed into a TTS factory (`TtsSynthesisContext`) |
 | `MediaConnectorContext` | `id`, flattened `config`, `dialogUuid`, `debug$` passed into factories |
 | `MediaProviderShared` | Optional per-dialog object from `createShared` |
+| `AsrProviderFactory` / `TtsProviderFactory` | Factory functions in `MediaProvidersDefinition` (`asr` / `tts` maps) |
 
 `defineMediaProviders` is an identity helper for typing. Factories must return objects that
-satisfy those interfaces (classes with `implements` recommended).
+satisfy those interfaces (classes with `implements` recommended). The argument is a
+`MediaProvidersDefinition`.
 
 ### Export shape (host module)
 
@@ -1286,11 +1491,18 @@ create ASR or want one subscription for the whole channel).
 | `ask(message, options?)`         | `Promise<string>`              | Single-shot completion (consumes SSE stream).    |
 | `stream(message, options?)`      | `Observable<LlmStreamChunk>`   | Token/chunk stream; use `chunk.content` for TTS. |
 | `extract(options?)`              | `Promise<Record<string, any>>` | Structured extraction via Omni extract API.      |
+| `createDialog(options)`          | `Promise<DialogInfo>`          | Create dialog (`CreateDialogOptions`, optional `payload`) (HTTP). |
+| `updateDialog(options)`          | `Promise<DialogInfo>`          | Patch dialog (`UpdateDialogOptions` / `payload`) (HTTP `/meta`). |
 | `makePersistentStream(options?)` | `PersistentLlmStreamHandle`    | Long-lived stream for multi-turn chat.           |
 
+`send()` returns a `PersistentLlmSendHandle` (`requestId`, per-turn `stream$`, `abort()`). Several sends may run in parallel on one socket.
+
+Persistent handle also exposes `createDialog` / `updateDialog` over Socket.IO (`dialog.create` / `dialog.update`).
+
 
 Common `LlmOptions`: `dialogUuid`, `agentUuid`, `role`, `hidden`, `name` (LLM speaker label — **not**
-the TTS credential `name`), `payload`, `debug`, `agentAliasFilter`, `currentAgentAlias`.
+the TTS credential `name`), `payload`, `history`, `debug`, `agentAliasFilter`, `currentAgentAlias`,
+`pseudoReasoning` (manual same-turn hint; skips the assigned reasoner LLM), `requestId`.
 
 ```ts
 const answer = await channel.llm.ask('Summarize the user request', {
@@ -1326,18 +1538,46 @@ const fields = await channel.llm.extract({
 });
 ```
 
-Persistent multi-turn stream:
+Persistent multi-turn stream (one Socket.IO connection, multiplexed by `requestId`):
 
 ```ts
+// HTTP: create / update dialog payload for prompt templates
+const created = await channel.llm.createDialog({
+  agentUuid: context.agentUuid,
+  payload: { customerName: 'Alex', language: 'ru' },
+});
+await channel.llm.updateDialog({
+  dialogUuid: context.dialogUuid,
+  payload: { ...created.payload, balance: 1200 },
+});
+
 const chat = channel.llm.makePersistentStream({
   agentUuid: context.agentUuid,
   dialogUuid: context.dialogUuid,
 });
 
+// Same over the persistent socket
+await chat.createDialog({
+  agentUuid: context.agentUuid,
+  payload: { customerName: 'Alex' },
+});
+await chat.updateDialog({ payload: { customerName: 'Alex', tier: 'gold' } });
+
 chat.stream$.pipe(map((c) => c.content)).subscribe((text) => logger.debug('LLM chunk', { text }));
 
 chat.send('What is my balance?');
 chat.send('And my last payment date?');
+
+// Parallel agents on the same socket:
+const realtime = chat.send(userText, {
+  currentAgentAlias: 'fast',
+  pseudoReasoning: 'User wants to cancel. Confirm identity first.',
+});
+const deep = chat.send(userText, { currentAgentAlias: 'researcher' });
+realtime.stream$.subscribe((c) => { /* TTS */ });
+deep.stream$.subscribe((c) => { /* notes / later TTS */ });
+// deep.abort(); // cancel only the deep turn
+
 chat.disconnect();
 ```
 
@@ -1375,6 +1615,8 @@ The return value is the `ScriptPhase` union — one of the phases in the table b
 | 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`                                   |
+| `dialing`            | `false`            | Live session with **no leg yet** — script opted into `outboundCallMode: 'script_dial'` and must `makeCall()` | any (ignored for phase; snapshot stays `'dialing'`)     |
+| `early`              | `false`            | Live session that started **before** the `200 OK` (campaign `'from_invite'` or inbound pre-answer). Not `channel.sip.state === 'early'` (RTP). Snapshot stays `'early'` after answer. | any (ignored for phase) |
 | `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`                      |
@@ -1419,6 +1661,16 @@ export default defineScript(async ({ channel, context, logger, platform }) => {
       logger.log('Inbound message', { text: context.inboundMessage?.payload });
       return { output: { phase } };
 
+    case 'dialing': {
+      const leg = await channel.sip.makeCall({});
+      await leg.sip.waitForAnswer();
+      await leg.audio.say('Hello.');
+      return;
+    }
+
+    case 'early':
+      await channel.sip.waitForAnswer();
+    // fall through to the conversation
     case 'online':
       channel.sip.answer();
       if ((context.attempt ?? 0) > 0) {
@@ -1694,7 +1946,7 @@ These APIs are available and are the intended tools for offline scripts:
 - `platform.messaging.send()` for outbound messages through the configured platform messaging transport.
 - `platform.call()` for scheduling outbound platform-managed calls.
 - `platform.dialog.entryPoint` and `platform.dialog.result` for updating dialog routing and outcome.
-- `channel.llm.ask()`, `channel.llm.stream()`, and `channel.llm.extract()` for Omni LLM operations.
+- `channel.llm.ask()`, `channel.llm.stream()`, `channel.llm.extract()`, `channel.llm.createDialog()`, and `channel.llm.updateDialog()` for Omni LLM operations.
 - `logger` for structured logs.
 
 Audio and telephony APIs are intentionally inert:

package/dist/define-script.d.ts

@@ -1,5 +1,6 @@
 import type { MediaChannel } from './types/media-channel';
 import type { ScriptLogger } from './types/logger';
+import type { ScriptCallOptions } from './types/call-options';
 import type { ScriptDialogContext, ScriptResult } from './types/script-context';
 import type { PlatformApi } from './types/platform';
 /**
@@ -42,6 +43,15 @@ export interface ScriptContext {
  * Return {@link ScriptResult} to persist output (and optional error), or void.
  */
 export type ScriptFn = (ctx: ScriptContext) => void | ScriptResult | Promise<void | ScriptResult>;
+/**
+ * A {@link ScriptFn} carrying the {@link ScriptCallOptions} passed to
+ * {@link defineScript}. The host reads them off the default export **before**
+ * the script runs, which is why they live on the function rather than in the
+ * returned {@link ScriptResult}.
+ */
+export type ScriptFnWithCallOptions = ScriptFn & {
+    readonly callOptions?: ScriptCallOptions;
+};
 /**
  * Mark the default export as a typed script entry point (identity wrapper; no runtime transform).
  *
@@ -53,7 +63,11 @@ export type ScriptFn = (ctx: ScriptContext) => void | ScriptResult | Promise<voi
  *   - Use **`channel`** for ASR/TTS (see {@link import('./types/asr-handle').AsrConfig.name},
  *     {@link import('./types/mixer').PlayOptions.name} for LE **`key_storage.name`** selection).
  *   - Use **`context.dialogParams`** / **`context.dialogUuid`** for routing; **`platform`** for NLU, calls, messaging.
- * @returns The same **`fn`** reference.
+ * @param options - Optional {@link ScriptCallOptions}. Unlike everything else in the
+ *   SDK these are read by the host **before** the script runs — they decide *when*
+ *   the session starts — so they are attached to the returned function instead of
+ *   being read from the handler.
+ * @returns The same **`fn`** reference, with `options` attached as `callOptions`.
  *
  * @example
  * ```ts
@@ -67,6 +81,21 @@ export type ScriptFn = (ctx: ScriptContext) => void | ScriptResult | Promise<voi
  *   });
  * });
  * ```
+ *
+ * @example Pick up the outbound leg from the INVITE — see {@link ScriptCallOptions.outboundCallMode}
+ * ```ts
+ * import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+ *
+ * export default defineScript(
+ *   async ({ channel, context }) => {
+ *     if (getScriptPhase(context) === 'early') {
+ *       await channel.sip.waitForAnswer();
+ *     }
+ *     await channel.audio.say('Hello!');
+ *   },
+ *   { outboundCallMode: 'from_invite' },
+ * );
+ * ```
  */
-export declare function defineScript(fn: ScriptFn): ScriptFn;
+export declare function defineScript(fn: ScriptFn, options?: ScriptCallOptions): ScriptFnWithCallOptions;
 //# sourceMappingURL=define-script.d.ts.map

package/dist/define-script.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-script.d.ts","sourceRoot":"","sources":["../src/define-script.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,OAAO,EAAE,YAAY,CAAC;IACtB,0FAA0F;IAC1F,MAAM,EAAE,YAAY,CAAC;IACrB,wFAAwF;IACxF,OAAO,EAAE,mBAAmB,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,EAAE,WAAW,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,CACrB,GAAG,EAAE,aAAa,KACf,IAAI,GAAG,YAAY,GAAG,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,QAAQ,CAEnD"}
+{"version":3,"file":"define-script.d.ts","sourceRoot":"","sources":["../src/define-script.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,OAAO,EAAE,YAAY,CAAC;IACtB,0FAA0F;IAC1F,MAAM,EAAE,YAAY,CAAC;IACrB,wFAAwF;IACxF,OAAO,EAAE,mBAAmB,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,EAAE,WAAW,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,CACrB,GAAG,EAAE,aAAa,KACf,IAAI,GAAG,YAAY,GAAG,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC;AAExD;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CAC1C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,YAAY,CAC1B,EAAE,EAAE,QAAQ,EACZ,OAAO,CAAC,EAAE,iBAAiB,GAC1B,uBAAuB,CASzB"}

package/dist/define-script.js

@@ -12,7 +12,11 @@ exports.defineScript = defineScript;
  *   - Use **`channel`** for ASR/TTS (see {@link import('./types/asr-handle').AsrConfig.name},
  *     {@link import('./types/mixer').PlayOptions.name} for LE **`key_storage.name`** selection).
  *   - Use **`context.dialogParams`** / **`context.dialogUuid`** for routing; **`platform`** for NLU, calls, messaging.
- * @returns The same **`fn`** reference.
+ * @param options - Optional {@link ScriptCallOptions}. Unlike everything else in the
+ *   SDK these are read by the host **before** the script runs — they decide *when*
+ *   the session starts — so they are attached to the returned function instead of
+ *   being read from the handler.
+ * @returns The same **`fn`** reference, with `options` attached as `callOptions`.
  *
  * @example
  * ```ts
@@ -26,8 +30,31 @@ exports.defineScript = defineScript;
  *   });
  * });
  * ```
+ *
+ * @example Pick up the outbound leg from the INVITE — see {@link ScriptCallOptions.outboundCallMode}
+ * ```ts
+ * import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+ *
+ * export default defineScript(
+ *   async ({ channel, context }) => {
+ *     if (getScriptPhase(context) === 'early') {
+ *       await channel.sip.waitForAnswer();
+ *     }
+ *     await channel.audio.say('Hello!');
+ *   },
+ *   { outboundCallMode: 'from_invite' },
+ * );
+ * ```
  */
-function defineScript(fn) {
-    return fn;
+function defineScript(fn, options) {
+    if (!options)
+        return fn;
+    // Non-enumerable so the export keeps looking like a plain function to
+    // anything that reflects over it (worker bridges, test doubles).
+    return Object.defineProperty(fn, 'callOptions', {
+        value: { ...options },
+        enumerable: false,
+        configurable: true,
+    });
 }
 //# sourceMappingURL=define-script.js.map

package/dist/define-script.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-script.js","sourceRoot":"","sources":["../src/define-script.ts"],"names":[],"mappings":";;AA2EA,oCAEC;AA5BD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,YAAY,CAAC,EAAY;IACvC,OAAO,EAAE,CAAC;AACZ,CAAC"}
+{"version":3,"file":"define-script.js","sourceRoot":"","sources":["../src/define-script.ts"],"names":[],"mappings":";;AAyGA,oCAYC;AAzDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,SAAgB,YAAY,CAC1B,EAAY,EACZ,OAA2B;IAE3B,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,sEAAsE;IACtE,iEAAiE;IACjE,OAAO,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,aAAa,EAAE;QAC9C,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE;QACrB,UAAU,EAAE,KAAK;QACjB,YAAY,EAAE,IAAI;KACnB,CAA4B,CAAC;AAChC,CAAC"}

package/dist/index.d.ts

@@ -29,7 +29,8 @@
  * 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';
+export type { ScriptContext, ScriptFn, ScriptFnWithCallOptions, } from './define-script';
+export type { ScriptCallOptions, OutboundCallMode, } from './types/call-options';
 export { defineMediaProviders } from './types/media-providers';
 export type { MediaProvidersDefinition, MediaConnectorContext, MediaProviderShared, AsrProviderFactory, TtsProviderFactory, ScriptAsrConnector, ScriptAsrConnectorError, ScriptTtsConnector, TtsSynthesisContext as ScriptTtsSynthesisContext, } from './types/media-providers';
 export type { ScriptDialogContext, ScriptPhase, ScriptRunTime, ScriptResult, PersistedScriptResult, ScriptError, AgentContext, AgentEnvSetOptions, StorageContextApi, } from './types/script-context';
@@ -38,7 +39,7 @@ export type { NluScriptApi, PlatformApi, DialogApi, ScheduleCallOptions, SendMes
 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 { ChannelLlm, LlmOptions, LlmStreamChunk, ExtractOptions, PersistentLlmStreamHandle, PersistentLlmSendHandle, CreateDialogOptions, UpdateDialogOptions, DialogInfo, } from './types/llm';
 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';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,YAAY,EACV,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,IAAI,yBAAyB,GACjD,MAAM,yBAAyB,CAAC;AAEjC,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,EACV,SAAS,EACT,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EACV,aAAa,EACb,QAAQ,EACR,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,YAAY,EACV,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,IAAI,yBAAyB,GACjD,MAAM,yBAAyB,CAAC;AAEjC,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,EACzB,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,UAAU,GACX,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,EACV,SAAS,EACT,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,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.map

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

package/dist/types/call-options.d.ts

@@ -0,0 +1,53 @@
+/**
+ * When the host hands a platform-dialed outbound leg to the script.
+ *
+ * - `'on_answer'` — the host dials and starts the script on the `200 OK`. The script
+ *   always gets an answered call, which is what a greeting, a turn watchdog and a
+ *   max-duration timer assume.
+ * - `'from_invite'` — the host starts the script **first**, then automatically
+ *   dials the campaign number on the same `channel`. The session is already
+ *   running when the INVITE goes out, so `progress$` / `sipSignal$` see 1xx and
+ *   a 4xx/5xx rejects `waitForAnswer()`. Phase is `'early'`; gate the greeting
+ *   on `channel.sip.waitForAnswer()`.
+ * - `'script_dial'` — the host does **not** dial. The script starts with no leg at all
+ *   (phase `'dialing'`) and opens one itself:
+ *
+ *   ```ts
+ *   const leg = await channel.sip.makeCall({ msisdn: context.calledNumber });
+ *   await leg.sip.waitForAnswer();
+ *   ```
+ *
+ *   The leg it gets back is the conversation channel — the one the script plays and
+ *   listens on. The channel the script starts with can only dial: it has no audio.
+ *   The first leg opened this way is the one the platform reports on (result,
+ *   `answer_date`, duration, recording), so a script that never dials leaves the
+ *   call row with no answer.
+ *
+ * Inbound legs are unaffected — they always start before the answer. `'from_invite'`
+ * additionally lets an inbound run report `'early'` instead of `'online'`.
+ *
+ * `answer_date` and billing never move: both come from the `200 OK`.
+ */
+export type OutboundCallMode = 'on_answer' | 'from_invite' | 'script_dial';
+/**
+ * Call-handling options a script declares for itself, passed as the second
+ * argument of {@link import('../define-script').defineScript}:
+ *
+ * ```ts
+ * export default defineScript(handler, { outboundCallMode: 'from_invite' });
+ * ```
+ *
+ * The host reads them off the default export **before** the session starts,
+ * because they decide *when* it starts. A script that passes nothing gets the
+ * documented defaults.
+ */
+export interface ScriptCallOptions {
+    /**
+     * Where the script picks up a platform-dialed outbound leg (campaign dialer,
+     * `platform.call`). See {@link OutboundCallMode} for what each mode implies.
+     *
+     * @defaultValue 'on_answer'
+     */
+    outboundCallMode?: OutboundCallMode;
+}
+//# sourceMappingURL=call-options.d.ts.map

package/dist/types/call-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-options.d.ts","sourceRoot":"","sources":["../../src/types/call-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,aAAa,GAAG,aAAa,CAAC;AAE3E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC"}

package/dist/types/call-options.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=call-options.js.map

package/dist/types/call-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-options.js","sourceRoot":"","sources":["../../src/types/call-options.ts"],"names":[],"mappings":""}

package/dist/types/llm.d.ts

@@ -22,6 +22,58 @@ export interface LlmOptions {
     debug?: boolean;
     /** Restrict which agent aliases may handle the request. */
     agentAliasFilter?: string[];
+    /**
+     * Manual same-turn pseudo-reasoning hint for the answering agent.
+     * When set, Omni skips the assigned reasoner LLM call and injects this text
+     * as a hidden reasoning message before the user turn.
+     */
+    pseudoReasoning?: string;
+    /**
+     * Multiplex id for persistent WS turns. Generated by `send()` when omitted.
+     * Echoed on every `stream.chunk` / `stream.complete` / `stream.error`.
+     */
+    requestId?: string;
+}
+/** Create an Omni dialog (HTTP or persistent `dialog.create`). */
+export interface CreateDialogOptions {
+    /** Omni agent UUID (required). */
+    agentUuid: string;
+    /** Optional fixed dialog UUID; Omni generates one when omitted. */
+    uuid?: string;
+    /** Extra dialog prompt appended after agent system prompt. */
+    prompt?: string;
+    /** Human-readable dialog name. */
+    name?: string;
+    /** Template variables persisted on the dialog (`dialog.payload`). */
+    payload?: Record<string, any>;
+    /** Optional seed history. */
+    history?: Array<{
+        role?: string;
+        content: string;
+        hidden?: boolean;
+        name?: string;
+    }>;
+}
+/** Patch Omni dialog fields (HTTP `/meta` or persistent `dialog.update`). */
+export interface UpdateDialogOptions {
+    /** Target dialog UUID; defaults to the channel / persistent stream dialog. */
+    dialogUuid?: string;
+    /** Required when the dialog may need to be created on first update. */
+    agentUuid?: string;
+    prompt?: string;
+    name?: string;
+    /** Replaces stored `dialog.payload` when set. */
+    payload?: Record<string, any>;
+    metadata?: Record<string, any>;
+    currentAgentAlias?: string;
+}
+/** Result of {@link ChannelLlm.createDialog} / {@link PersistentLlmStreamHandle.createDialog}. */
+export interface DialogInfo {
+    uuid: string;
+    agentUuid?: string;
+    payload?: Record<string, any> | null;
+    prompt?: string | null;
+    currentAgentAlias?: string | null;
 }
 /** Options for **`channel.llm.extract`**. All fields except `dialogUuid` are forwarded to Omni extract. */
 export interface ExtractOptions {
@@ -48,14 +100,38 @@ export interface LlmStreamChunk {
     event: any;
     toolMessages?: any[];
     raw: Record<string, any>;
+    /** Set on persistent WS chunks so parallel sends on one socket can be demuxed. */
+    requestId?: string;
+    /** Alias that produced this chunk when the backend includes it. */
+    currentAgentAlias?: string;
+}
+/**
+ * One in-flight turn on a {@link PersistentLlmStreamHandle}.
+ * Several sends may run in parallel on the same Socket.IO connection.
+ */
+export interface PersistentLlmSendHandle {
+    readonly requestId: string;
+    readonly stream$: Observable<LlmStreamChunk>;
+    /** Cancel this turn only (`stream.abort`); other in-flight sends keep running. */
+    abort(): void;
 }
 /**
  * Long-lived LLM Socket.IO stream — amortizes connection setup across many user turns.
  */
 export interface PersistentLlmStreamHandle {
+    /** Merged chunks from every in-flight `send` (filter by `chunk.requestId` if needed). */
     readonly stream$: Observable<LlmStreamChunk>;
-    /** Send one user/assistant turn over the existing stream; options override defaults for this send only. */
-    send(message: string, options?: LlmOptions): void;
+    /**
+     * Send one turn over the existing socket.
+     * Returns a per-turn stream so several agents can run in parallel on one connection.
+     */
+    send(message: string, options?: LlmOptions): PersistentLlmSendHandle;
+    /** Create a dialog (and optional payload) over the persistent socket (`dialog.create`). */
+    createDialog(options: CreateDialogOptions): Promise<DialogInfo>;
+    /** Update dialog fields / payload over the persistent socket (`dialog.update`). */
+    updateDialog(options: UpdateDialogOptions): Promise<DialogInfo>;
+    /** Cancel one in-flight turn by `requestId` (`stream.abort`). */
+    abort(requestId: string): void;
     /** Close the underlying Socket.IO stream without destroying the handle object. */
     disconnect(): void;
     /** Re-open the underlying Socket.IO stream after {@link disconnect}. */
@@ -69,6 +145,10 @@ export interface ChannelLlm {
     stream(message: string, options?: LlmOptions): Observable<LlmStreamChunk>;
     /** Structured extraction / JSON-style fill from conversation context via Omni extract. */
     extract(options?: ExtractOptions): Promise<Record<string, any>>;
+    /** Create an Omni dialog with optional payload (HTTP `POST /v1/chat`). */
+    createDialog(options: CreateDialogOptions): Promise<DialogInfo>;
+    /** Update Omni dialog payload / prompt / alias (HTTP `POST /v1/chat/:uuid/meta`). */
+    updateDialog(options: UpdateDialogOptions): Promise<DialogInfo>;
     /**
      * Open a persistent Omni chat stream.
      * @param options - Default **`agentUuid`**, **`dialogUuid`**, etc.; per-**`send`** overrides allowed.

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

@@ -1 +1 @@
-{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/types/llm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAEvC,qFAAqF;AACrF,MAAM,WAAW,UAAU;IACzB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B,uCAAuC;IACvC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,2GAA2G;AAC3G,MAAM,WAAW,cAAc;IAC7B,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,+CAA+C;AAC/C,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,EAAE,GAAG,CAAC;IACX,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,cAAc,CAAC,CAAC;IAC7C,2GAA2G;IAC3G,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAClD,kFAAkF;IAClF,UAAU,IAAI,IAAI,CAAC;IACnB,wEAAwE;IACxE,SAAS,IAAI,IAAI,CAAC;CACnB;AAED,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,4GAA4G;IAC5G,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5D,gFAAgF;IAChF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAC1E,0FAA0F;IAC1F,OAAO,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAChE;;;OAGG;IACH,oBAAoB,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,yBAAyB,CAAC;CACvE"}
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/types/llm.ts"],"names":[],"mappings":"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"}

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

@@ -168,6 +168,27 @@ export interface ScriptDialogContext {
      * {@link import('./platform').DialogApi.entryPoint} (`platform.dialog.entryPoint`).
      */
     entryPoint?: string;
+    /**
+     * True when this live session started **before** the final 200 OK — the leg had
+     * media (183 with SDP) but was not answered yet. Snapshot at script start: it
+     * describes how the run began and does not flip when the answer arrives; use
+     * `channel.sip.isAnswered` / `answered$` for the live state.
+     *
+     * Set by the host only for scripts that opted in via
+     * {@link import('./call-options').ScriptCallOptions.outboundCallMode} `'from_invite'`,
+     * and surfaced as {@link ScriptPhase} `'early'` by {@link getScriptPhase}.
+     */
+    startedBeforeAnswer?: boolean;
+    /**
+     * True when this live session started with **no leg at all** — the script dials one
+     * itself via `channel.sip.makeCall()`. Set only for scripts that opted in via
+     * {@link import('./call-options').ScriptCallOptions.outboundCallMode} `'script_dial'`, and
+     * surfaced as {@link ScriptPhase} `'dialing'` by {@link getScriptPhase}.
+     *
+     * Like {@link startedBeforeAnswer}, a snapshot of how the run began: it stays true after
+     * the script opens a leg.
+     */
+    startedWithoutLeg?: boolean;
     /** Current recall attempt number for this dialog (from `dialog.params.attempt`, starts at 0). */
     attempt?: number;
     /**
@@ -231,11 +252,19 @@ export interface ScriptRunTime {
  * High-level phase of a script execution lifecycle. Useful for branching logic
  * between pre-call preparation, the live call, and post-call processing.
  */
-export type ScriptPhase = 'before_call' | 'online' | 'after_call_success' | 'after_call_failed' | 'messaging' | 'recall' | 'headless_other';
+export type ScriptPhase = 'before_call' | 'dialing' | 'early' | 'online' | 'after_call_success' | 'after_call_failed' | 'messaging' | 'recall' | 'headless_other';
 /**
  * Determines which phase of the dialog lifecycle the script is currently executing in.
  *
  * - `before_call` — headless run that typically schedules an outbound call.
+ * - `dialing` — live session that started with no leg: the script opens one itself with
+ *   `channel.sip.makeCall()` and talks on the channel that returns. Only scripts that opt
+ *   in via {@link import('./call-options').ScriptCallOptions.outboundCallMode} `'script_dial'`
+ *   ever see it.
+ * - `early` — live SIP/media session that started before the final answer. Only scripts
+ *   that opt in via {@link import('./call-options').ScriptCallOptions.outboundCallMode}
+ *   `'from_invite'` ever see it; await `channel.sip.waitForAnswer()` to reach the
+ *   conversation.
  * - `online` — live SIP/media session (voice call active).
  * - `after_call_success` — headless run after a successful call completion.
  * - `after_call_failed` — headless run after call failure (no answer, reject, etc.).

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

@@ -15,6 +15,14 @@ const RECALL_ENTRY_POINTS = new Set(['on_recall', 'recall']);
  * Determines which phase of the dialog lifecycle the script is currently executing in.
  *
  * - `before_call` — headless run that typically schedules an outbound call.
+ * - `dialing` — live session that started with no leg: the script opens one itself with
+ *   `channel.sip.makeCall()` and talks on the channel that returns. Only scripts that opt
+ *   in via {@link import('./call-options').ScriptCallOptions.outboundCallMode} `'script_dial'`
+ *   ever see it.
+ * - `early` — live SIP/media session that started before the final answer. Only scripts
+ *   that opt in via {@link import('./call-options').ScriptCallOptions.outboundCallMode}
+ *   `'from_invite'` ever see it; await `channel.sip.waitForAnswer()` to reach the
+ *   conversation.
  * - `online` — live SIP/media session (voice call active).
  * - `after_call_success` — headless run after a successful call completion.
  * - `after_call_failed` — headless run after call failure (no answer, reject, etc.).
@@ -23,8 +31,11 @@ const RECALL_ENTRY_POINTS = new Set(['on_recall', 'recall']);
  * - `headless_other` — any other headless invocation not matching the above.
  */
 function getScriptPhase(context) {
-    if (!context.headless)
-        return 'online';
+    if (!context.headless) {
+        if (context.startedWithoutLeg)
+            return 'dialing';
+        return context.startedBeforeAnswer ? 'early' : 'online';
+    }
     const ep = context.entryPoint?.trim().toLowerCase() ?? '';
     if (AFTER_CALL_SUCCESS_ENTRY_POINTS.has(ep))
         return 'after_call_success';

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

@@ -1 +1 @@
-{"version":3,"file":"script-context.js","sourceRoot":"","sources":["../../src/types/script-context.ts"],"names":[],"mappings":";;AA4RA,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":";;AA2TA,wCAiBC;AA/CD,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;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,cAAc,CAAC,OAA4B;IACzD,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtB,IAAI,OAAO,CAAC,iBAAiB;YAAE,OAAO,SAAS,CAAC;QAChD,OAAO,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC1D,CAAC;IAED,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

@@ -6,6 +6,9 @@ Each file exports one `defineScript` handler. The host **always** invokes that s
 
 | File | Topic |
 |------|--------|
+| [outbound-on-answer.ts](./outbound-on-answer.ts) | Campaign outbound on `200 OK` (`outboundCallMode: 'on_answer'`, the default) |
+| [outbound-from-invite.ts](./outbound-from-invite.ts) | Campaign outbound from INVITE (`outboundCallMode: 'from_invite'`) |
+| [outbound-script-dial.ts](./outbound-script-dial.ts) | Script dials the campaign leg (`outboundCallMode: 'script_dial'`) |
 | [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` |

package/examples/outbound-from-invite.ts

@@ -0,0 +1,30 @@
+/**
+ * Campaign outbound that starts at INVITE (`outboundCallMode: 'from_invite'`).
+ *
+ * The host raises the script first, then dials the campaign number on the same
+ * `channel`. 1xx lands on `progress$`; a 4xx/5xx rejects `waitForAnswer()`.
+ * Gate the greeting on the answer so it does not play into ringback.
+ *
+ * `getScriptPhase` stays `'early'` for the whole live run. Read
+ * `channel.sip.isAnswered` for the live state. Billing stays on the 200 OK.
+ */
+import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+
+export default defineScript(
+  async ({ channel, logger, context }) => {
+    if (getScriptPhase(context) === 'early') {
+      channel.sip.progress$.subscribe(({ statusCode }) => {
+        logger.log('progress', { statusCode });
+      });
+      try {
+        await channel.sip.waitForAnswer();
+      } catch (err) {
+        logger.warn('outbound failed', { err });
+        return;
+      }
+    }
+
+    await channel.audio.say('Hello!');
+  },
+  { outboundCallMode: 'from_invite' },
+);

package/examples/outbound-on-answer.ts

@@ -0,0 +1,18 @@
+/**
+ * Campaign outbound that starts on the 200 OK (`outboundCallMode: 'on_answer'`).
+ *
+ * This is the default: omit the second argument of `defineScript` and you get
+ * the same timing. The host dials first and holds the script until answer.
+ * Busy / no-answer / 4xx never reach this handler.
+ *
+ * Talk on `channel`. Do not `makeCall()` the campaign number — the host
+ * already did. Billing stays on the 200 OK.
+ */
+import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+
+export default defineScript(async ({ channel, context }) => {
+  // Live outbound: always 'online'. Headless before_call / after_call_* still apply.
+  if (getScriptPhase(context) !== 'online') return;
+
+  await channel.audio.say('Hello!');
+});

package/examples/outbound-script-dial.ts

@@ -0,0 +1,20 @@
+/**
+ * Campaign outbound where the script opens the leg (`outboundCallMode: 'script_dial'`).
+ *
+ * The host does not send an INVITE. Phase is `'dialing'`; the starting `channel`
+ * can only dial. Conversation is on the channel `makeCall()` returns.
+ * `makeCall({})` uses the campaign msisdn + the call row's trunk.
+ *
+ * The first successful dial is the campaign row (result, `answer_date`, recording).
+ */
+import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+
+export default defineScript(
+  async (ctx) => {
+    const phase = getScriptPhase(ctx.context);
+    const channel =
+      phase === 'dialing' ? await ctx.channel.sip.makeCall({}) : ctx.channel;
+    await channel.audio.say('Hello!');
+  },
+  { outboundCallMode: 'script_dial' },
+);

package/package.json

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