@xema/omni-protocol 0.1.135 → 0.1.137
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +9 -2
- package/dist/validation.js +6 -7
- package/guide/agent.md +12 -5
- package/guide/phone.md +10 -0
- package/guide.md +1 -1
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -153,8 +153,11 @@ export interface PhoneState {
|
|
|
153
153
|
muted?: true;
|
|
154
154
|
/** When the status began, counted from the provider's clock. Omitted rather than invented. */
|
|
155
155
|
since?: IsoTimestamp;
|
|
156
|
-
/**
|
|
157
|
-
|
|
156
|
+
/**
|
|
157
|
+
* The calls on the phone; `[]` when idle. None under `unregistered` or `off-hook`. Omitted only
|
|
158
|
+
* where the provider cannot see the calls on the device: present, it is every one of them.
|
|
159
|
+
*/
|
|
160
|
+
channels?: PhoneChannel[];
|
|
158
161
|
}
|
|
159
162
|
/** Every idle capability a provider may declare. Only voice may `dial`; the channel arm says so. */
|
|
160
163
|
export declare const IDLE_CAPABILITIES: readonly ["dial", "personalBrowser", "calendar", "contacts"];
|
|
@@ -809,6 +812,10 @@ export interface OutcomeCode {
|
|
|
809
812
|
group?: string;
|
|
810
813
|
}
|
|
811
814
|
export interface OutcomeRules {
|
|
815
|
+
/**
|
|
816
|
+
* The agent's `complete` carries a code. A person's close chooses an outcome; only the provider's
|
|
817
|
+
* own close, when a `provider-automatic` wrap runs out, may carry none.
|
|
818
|
+
*/
|
|
812
819
|
required?: boolean;
|
|
813
820
|
notes?: "required" | "optional" | "none";
|
|
814
821
|
codes?: OutcomeCode[];
|
package/dist/validation.js
CHANGED
|
@@ -1374,11 +1374,6 @@ function validateTaskInto(task, context, path, into) {
|
|
|
1374
1374
|
if (capabilities.browsers === true && Array.isArray(task.browsers) && task.browsers.length === 0) {
|
|
1375
1375
|
into.add("task.browsers.required", `${path}.browsers`, "a task that declares capabilities.browsers supplies at least one; with none, omit the capability");
|
|
1376
1376
|
}
|
|
1377
|
-
// An outcome is given in wrap, by the agent: a provider that completes the task itself cannot
|
|
1378
|
-
// wait for one, and a task with no wrap has nowhere to take one.
|
|
1379
|
-
if (isPlainObject(capabilities.outcomes) && capabilities.outcomes.required === true) {
|
|
1380
|
-
into.require(task.completionMode !== "provider-automatic", "task.outcomes.required.mode", `${path}.capabilities.outcomes.required`, "a required outcome is the agent's to give, so the task completes on the agent's command; provider-automatic completion cannot wait for it");
|
|
1381
|
-
}
|
|
1382
1377
|
// Under agent-command the allowance is the expected wrap, shown and never acted on: the agent
|
|
1383
1378
|
// completes whenever they are done, so there is always a wrap to collect the code in.
|
|
1384
1379
|
if (capabilities.outcomes !== undefined) {
|
|
@@ -2443,8 +2438,12 @@ function validatePhoneStateInto(value, path, context, into) {
|
|
|
2443
2438
|
if (value.since !== undefined)
|
|
2444
2439
|
into.timestamp(value.since, "phone.since", `${path}.since`);
|
|
2445
2440
|
// The phone's own calls: one active at most, any number held, and none on a phone that cannot carry one.
|
|
2446
|
-
|
|
2447
|
-
|
|
2441
|
+
// Omitted, the provider cannot see the device's calls, and there is nothing to hold them to.
|
|
2442
|
+
if (value.channels === undefined) {
|
|
2443
|
+
// The status still stands on its own.
|
|
2444
|
+
}
|
|
2445
|
+
else if (!Array.isArray(value.channels)) {
|
|
2446
|
+
into.add("phone.channels.shape", `${path}.channels`, "channels is the phone's calls, an array: [] when idle, omitted only where the provider cannot see them");
|
|
2448
2447
|
}
|
|
2449
2448
|
else {
|
|
2450
2449
|
let active = 0;
|
package/guide/agent.md
CHANGED
|
@@ -164,7 +164,7 @@ time. Runtime conformance checks also require the task channel to match its prov
|
|
|
164
164
|
| `previewEndsInSeconds` | Voice only, in `preview`: how long the preparation has left, in whole seconds from this publication, restated on every publication that carries it. Absent, the agent has as long as they need without a preparation countdown. Always with `atDeadline`. See **Preview: the agent presses Call** in `guide/voice.md`. |
|
|
165
165
|
| `atDeadline` | Voice only, in `preview`, with `previewEndsInSeconds`: what the system does when it runs out -- `provider-dials` makes the provider initiate dialing, `host-dials` makes the agent application issue Call, `waits` keeps the task in preview awaiting the agent. |
|
|
166
166
|
| `reference` | Optional agent-facing reference such as a case, call, conversation, ticket, or message number. It is distinct from the protocol `id`. |
|
|
167
|
-
| `completionMode` | `agent-command` waits for the channel's `complete` command; `provider-automatic` completes without one, and takes the agent's `complete` as finishing early. A required outcome
|
|
167
|
+
| `completionMode` | `agent-command` waits for the channel's `complete` command; `provider-automatic` completes without one, and takes the agent's `complete` as finishing early. A required outcome binds the agent's `complete` under either mode. |
|
|
168
168
|
| `wrapAllowance` | Fixed time allowed to complete the task after primary interaction ends. For real-time audio, it begins after `task-audio-ended`. Required under `provider-automatic`, where the provider acts on it. Optional under `agent-command`: omitted says the provider imposes no deadline, and Omni counts nothing down; stated, it is the expected wrap, shown and never acted on. `0` under `provider-automatic` is no wrap at all, so such a task publishes no `outcomes` (`task.outcomes.wrapAllowance`). |
|
|
169
169
|
| `wrapEndsInSeconds` | In `completing`, wherever `wrapAllowance` is stated: how much of the wrap is left, in whole seconds from this publication, restated on every publication that carries it (`task.completing.wrapEndsInSeconds`, `.required`, `.unexpected`). A reloaded agent computer and a lead's screen count down the same number. See **Completion timing**. |
|
|
170
170
|
| `attributes` | Optional ordered, typed `TaskAttribute` entries with keys unique within the task. Each contact or timestamp is a separate array item; new attribute shapes require new union members. |
|
|
@@ -254,10 +254,17 @@ with no wrap at all -- `provider-automatic` with `wrapAllowance: 0` -- has nothi
|
|
|
254
254
|
the command is refused there (`command.complete.wrapAllowance`). An ending the agent asked for says
|
|
255
255
|
so, `completed` with `by: "agent"`, whichever mode the task was under.
|
|
256
256
|
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
257
|
+
Migration: a required outcome under `provider-automatic` is no longer refused; the former
|
|
258
|
+
`task.outcomes.required.mode` rule is gone.
|
|
259
|
+
|
|
260
|
+
**A required outcome binds the agent's close.** `required: true` says the agent's `complete`
|
|
261
|
+
carries a code from the list (`command.complete.outcome.required`): a person who closes the task
|
|
262
|
+
chooses how it went. It says nothing about the provider's own close. Under `agent-command` the
|
|
263
|
+
task waits for the agent, so every close carries a code. Under `provider-automatic` the agent may
|
|
264
|
+
still close early, with a code, and when the wrap runs out the provider closes it with none, since
|
|
265
|
+
nobody chose one. The agent computer reads `required` and asks for a code before it sends
|
|
266
|
+
`complete`, so the agent is never told one is needed only after pressing it. Optional outcomes
|
|
267
|
+
ride on either mode; the agent gives one if they want to. And a code is given in wrap,
|
|
261
268
|
so a `provider-automatic` task with `wrapAllowance: 0` publishes no `outcomes` at all
|
|
262
269
|
(`task.outcomes.wrapAllowance`).
|
|
263
270
|
|
package/guide/phone.md
CHANGED
|
@@ -305,6 +305,8 @@ const busy: PhoneState = { phone: "hardphone", status: "ready", muted: true, cha
|
|
|
305
305
|
const internal: PhoneState = { phone: "hardphone", status: "ready", channels: [{ state: "active", since: "2026-09-12T11:02:00Z" }] };
|
|
306
306
|
// a hardphone the platform lost
|
|
307
307
|
const down: PhoneState = { phone: "hardphone", status: "unregistered", since: "2026-09-12T10:41:00Z", channels: [] };
|
|
308
|
+
// a platform that sees the registration but not the calls on the device
|
|
309
|
+
const unseen: PhoneState = { phone: "softphone", status: "unregistered", since: "2026-09-12T10:41:00Z" };
|
|
308
310
|
```
|
|
309
311
|
|
|
310
312
|
**The device.** `status` is the phone itself: `ready` is registered and usable, idle or busy, and
|
|
@@ -333,6 +335,14 @@ started, `held` with the task `paused`, `ringing` with the task `pending` or its
|
|
|
333
335
|
phone carries every call the agent computer is on. A channel naming no task is the phone's alone, and the
|
|
334
336
|
agent computer shows it as a call it cannot act on.
|
|
335
337
|
|
|
338
|
+
**Omitted only where the provider cannot see them.** Some platforms know whether the phone is
|
|
339
|
+
registered but not which calls are on it: an internal call, a lead's listening leg. Such a
|
|
340
|
+
provider still declares `phoneStatus` and publishes the status, and leaves `channels` out. Omitted
|
|
341
|
+
and empty are different claims: `[]` says the phone is idle, and no `channels` says nothing about
|
|
342
|
+
its calls, so none of the channel checks apply. Present, the list is every call on the device.
|
|
343
|
+
Leaving the status out instead would hide a phone that cannot take a call, which is the one thing
|
|
344
|
+
the agent and the lead most need to see.
|
|
345
|
+
|
|
336
346
|
**The mute is the phone's, and it silences whatever is active.** It is one flag on the phone, not
|
|
337
347
|
a property of a channel: whichever channel is active is silent while it is set, and the held
|
|
338
348
|
channels are unaffected. Who owns it follows the phone. On a hardphone the mute button is the
|
package/guide.md
CHANGED