@xema/omni-protocol 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -375,7 +375,22 @@ export interface TaskHandlingStep {
      */
     by?: UserId;
 }
-export interface Task<C extends Channel = Channel> {
+/**
+ * How the task ends, and how long after handling the provider allows for it.
+ *
+ * The allowance is coupled to the mode. Under `provider-automatic` the provider acts on it, so it
+ * is required. Under `agent-command` the provider will not complete the task itself, so it may
+ * omit the allowance to say it imposes no deadline -- and Omni then counts nothing down. Omitted
+ * and `0` are different claims: no deadline to see, and a deadline of now.
+ */
+export type TaskCompletion = {
+    completionMode: "agent-command";
+    completionAllowance?: DurationSeconds;
+} | {
+    completionMode: "provider-automatic";
+    completionAllowance: DurationSeconds;
+};
+export type Task<C extends Channel = Channel> = {
     id: TaskId;
     title: string;
     channel: C;
@@ -387,11 +402,9 @@ export interface Task<C extends Channel = Channel> {
     phase: TaskPhase;
     /** The identifier an agent reads back to a customer, where the provider has one. */
     reference?: string;
-    completionMode: CompletionMode;
-    completionAllowance: DurationSeconds;
     attributes?: TaskAttribute[];
     handlingHistory?: TaskHandlingStep[];
-}
+} & TaskCompletion;
 /** What the provider wants of Omni's acceptance policy for one offer. */
 export type AcceptanceMode = "no-preference" | "require-agent-acceptance" | "require-automatic-acceptance";
 export type TaskOutcome = {

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Connection, type Snapshot, type Task, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type DialRequest, type TaskCommandRequest } from "./index.js";
+import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Connection, type Snapshot, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type DialRequest, type TaskCommandRequest } from "./index.js";
 import { type ProtocolViolation } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation } from "./validation.js";
 export interface AdapterContractResult {
@@ -45,10 +45,13 @@ export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakApp
 export declare function assertDialIdempotency(connection: Pick<Connection, "dial">, request: DialRequest): Promise<void>;
 /**
  * Validates the deadline derived from media end and the task's fixed wrap allowance.
- * `toleranceMs` absorbs scheduler jitter in a real implementation; pass 0 to demand
- * an exact match.
+ *
+ * A task with no allowance has no deadline, so `observedDeadline` must then be `undefined`: a
+ * host counting down what the provider left open is the violation, and so is a host counting
+ * nothing down when the provider set a clock. `toleranceMs` absorbs scheduler jitter in a real
+ * implementation; pass 0 to demand an exact match.
  */
-export declare function assertWrapTimeout(task: Pick<Task, "completionAllowance">, mediaEndedAt: string, observedDeadline: string, toleranceMs?: number): void;
+export declare function assertWrapTimeout(task: Pick<TaskCompletion, "completionMode" | "completionAllowance">, mediaEndedAt: string, observedDeadline: string | undefined, toleranceMs?: number): void;
 /** One browser in one task of one provider. `providerId` is `Manifest.id`, never `displayName`. */
 export type BrowserIsolationScenario = BrowserSessionKeyInput;
 /** Validates whether two task-browser definitions should share one browser session. */

package/dist/testing.js

@@ -245,10 +245,22 @@ export async function assertDialIdempotency(connection, request) {
 }
 /**
  * Validates the deadline derived from media end and the task's fixed wrap allowance.
- * `toleranceMs` absorbs scheduler jitter in a real implementation; pass 0 to demand
- * an exact match.
+ *
+ * A task with no allowance has no deadline, so `observedDeadline` must then be `undefined`: a
+ * host counting down what the provider left open is the violation, and so is a host counting
+ * nothing down when the provider set a clock. `toleranceMs` absorbs scheduler jitter in a real
+ * implementation; pass 0 to demand an exact match.
  */
 export function assertWrapTimeout(task, mediaEndedAt, observedDeadline, toleranceMs = 1_000) {
+    if (task.completionAllowance === undefined) {
+        if (observedDeadline !== undefined) {
+            throw new Error(`Wrap deadline mismatch: the task states no allowance, so there is no deadline, received ${observedDeadline}`);
+        }
+        return;
+    }
+    if (observedDeadline === undefined) {
+        throw new Error(`Wrap deadline mismatch: the task allows ${task.completionAllowance}s, but no deadline was observed`);
+    }
     const ended = Date.parse(mediaEndedAt);
     const deadline = Date.parse(observedDeadline);
     if (Number.isNaN(ended) || Number.isNaN(deadline))

package/dist/validation.js

@@ -517,7 +517,15 @@ function validateTaskInto(task, context, path, into) {
     into.filled(task.taskType, "task.taskType", `${path}.taskType`, "a task needs a task type");
     into.oneOf(task.phase, TASK_PHASES, "task.phase", `${path}.phase`);
     into.oneOf(task.completionMode, COMPLETION_MODES, "task.completionMode", `${path}.completionMode`);
-    into.require(isDurationSeconds(task.completionAllowance), "task.completionAllowance", `${path}.completionAllowance`, "completionAllowance must be a whole number of seconds, zero or more");
+    // The allowance is coupled to the mode: a provider that will complete the task itself is going
+    // to act on the allowance, so it must state one; a provider waiting for `complete` may omit it
+    // to say it imposes no deadline. Present, it is a duration either way.
+    if (task.completionAllowance === undefined) {
+        into.require(task.completionMode !== "provider-automatic", "task.completionAllowance.required", `${path}.completionAllowance`, "provider-automatic completion needs an allowance to act on");
+    }
+    else {
+        into.require(isDurationSeconds(task.completionAllowance), "task.completionAllowance", `${path}.completionAllowance`, "completionAllowance must be a whole number of seconds, zero or more, or omitted under agent-command");
+    }
     // The channel is fixed per provider by its manifest, so a task claiming another one is a
     // task Omni would render with the wrong controls.
     into.require(task.channel === context.channel, "task.channel", `${path}.channel`, `a ${context.channel} provider may not publish a ${String(task.channel)} task`);

package/guide.md

@@ -416,6 +416,10 @@ type TaskHandlingStep = {
   by?: UserId;
 };
 
+type TaskCompletion =
+  | { completionMode: "agent-command"; completionAllowance?: DurationSeconds }
+  | { completionMode: "provider-automatic"; completionAllowance: DurationSeconds };
+
 type Task<C extends Channel = Channel> = {
   id: TaskId;
   title: string;
@@ -426,11 +430,9 @@ type Task<C extends Channel = Channel> = {
   contact?: Contact;
   phase: TaskPhase;
   reference?: string;
-  completionMode: CompletionMode;
-  completionAllowance: DurationSeconds;
   attributes?: TaskAttribute[];
   handlingHistory?: TaskHandlingStep[];
-};
+} & TaskCompletion;
 
 type AcceptanceMode =
   | "no-preference"
@@ -1616,7 +1618,7 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `phase` | Current canonical task phase: `pending`, `confirmed`, `preparing`, `in-progress`, `paused`, or `completing`. |
 | `reference` | Optional agent-facing reference such as a case, call, conversation, ticket, or message number. It is distinct from the protocol `id`. |
 | `completionMode` | `agent-command` waits for the channel's `complete` command; `provider-automatic` completes without one. |
-| `completionAllowance` | Fixed time allowed to complete the task after primary handling ends. For real-time media, it begins after `task-media-ended`. |
+| `completionAllowance` | Fixed time allowed to complete the task after primary handling ends. For real-time media, it begins after `task-media-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. |
 | `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. |
 | `handlingHistory` | Optional ordered handling history for this currently open task. It is live task data, not a permanent archive. |
 
@@ -1690,9 +1692,25 @@ In this example, the agent has two minutes after sending the email to add notes,
 disposition, and complete the task.
 
 `0` means completion may happen immediately. With `provider-automatic`, the provider may complete
-without waiting for a command; with `agent-command`, it still waits for `complete`. There is no
-value meaning "unlimited": a provider that does not want a deadline keeps the task `in-progress` or
-`paused` and moves it to `completing` only when the clock should start.
+without waiting for a command; with `agent-command`, it still waits for `complete`.
+
+There is no value meaning "unlimited", because a number that is not a duration would be read as
+one. A provider that imposes no deadline says so by **omitting** `completionAllowance`, which
+only `agent-command` permits: the provider will not complete the task itself, so there is nothing
+for a deadline to trigger, and Omni counts nothing down. **Omitted and empty are different
+claims** applies -- omitted says there is no deadline to see, where `0` says the deadline is now.
+Under `provider-automatic` the field is required, because the provider is going to act on it.
+
+```ts
+const untimedWrap = {
+  completionMode: "agent-command",
+} satisfies Pick<Task<"voice">, "completionMode" | "completionAllowance">;
+```
+
+Here the customer has hung up, `task-media-ended` has been sent on time, the task is `completing`,
+and the agent takes as long as the work needs. Moving the task to `completing` late to avoid a
+deadline is not an alternative on a media channel: the clock starts at a real event, and delaying
+that event would falsify the phase and everything timed from it.
 
 ```ts
 const immediateProviderCompletion = {
@@ -2666,7 +2684,8 @@ They are published as `OMNI_FAILURE_CODES`.
 #### Provider instants are read against a provider clock
 
 Every deadline in this contract is a provider instant that Omni counts down: `allocationExpiresAt`,
-`preparationEndsAt`, and the wrap deadline of `task-media-ended` plus `completionAllowance`.
+`preparationEndsAt`, and the wrap deadline of `task-media-ended` plus `completionAllowance` where
+one is stated.
 Comparing those against the host clock is wrong by whatever the two machines disagree by, and the
 damaging direction is early — **Accept** withdrawn from an offer still ringing, a wrap timer
 expiring before the agent has finished.
@@ -2913,7 +2932,7 @@ cannot be established from TypeScript structure alone.
 | `assertDeniedAndRetriedBreak(states)` | A denial transitions directly to `not-requested`; a later request can still be granted. |
 | `assertCommandIdempotency(connection, request)` | Retrying a task command does not repeat its side effect. |
 | `assertDialIdempotency(connection, request)` | Retrying a dial command does not place another call. |
-| `assertWrapTimeout(task, mediaEndedAt, deadline, toleranceMs?)` | The wrap deadline equals media end plus the task allowance, within a tolerance that defaults to 1000ms. |
+| `assertWrapTimeout(task, mediaEndedAt, deadline, toleranceMs?)` | The wrap deadline equals media end plus the task allowance, within a tolerance that defaults to 1000ms; a task with no allowance has no deadline, and one observed is the violation. |
 | `assertBrowserIsolationAndReuse(left, right, expected)` | Browser reuse follows only the declared isolation scheme. |
 | `assertNoBrowserSessionKeyCollisions(scenarios)` | No two distinct scenarios derive the same session key. Feed it adversarial names. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xema/omni-protocol",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",