@xema/omni-protocol 0.1.116 → 0.1.117

package/dist/index.d.ts

@@ -246,7 +246,8 @@ export interface SecretStore {
  * A small store for one login's operational state -- what an adapter holds about open work that
  * its platform cannot hold for it, such as the interaction legs a host reported. Kept by the host for
  * the life of the login, across a reload of the host, and cleared at sign-out. Never for anything
- * sensitive: that is `SecretStore`, whose contract is that a host may clear it aggressively.
+ * sensitive: that is `SecretStore`, whose contract is that a host may clear it aggressively, and
+ * clears it once the session has ended.
  */
 export interface LoginStore {
     get(key: string): Promise<string | undefined>;
@@ -318,6 +319,13 @@ export interface UserCapabilities {
  * Only `authenticated` and `refreshing` know who the agent is and what they may do, and only
  * `authenticated` has something to expire. A state carrying more than it knows is a state Omni
  * would render as fact.
+ *
+ * `signed-out` is the agent's own Sign out on this agent computer, and nothing else. `terminated`
+ * is a session ended from outside it -- a supervisor, the agent on another screen, the platform
+ * itself -- and says who: a person by id, or `provider` where no person was behind it, with the
+ * reason as a failure that is never retryable. `expired` is a session whose time ran out or whose
+ * refresh is failing. The stored secrets go with every ending: signed out, terminated, and expired
+ * unless its failure says `retryable: true`.
  */
 export type AuthenticationState = {
     status: "signed-out";
@@ -336,6 +344,13 @@ export type AuthenticationState = {
     status: "expired";
     identity?: User;
     failure?: AuthenticationFailure;
+} | {
+    status: "terminated";
+    by: UserId | "provider";
+    identity?: User;
+    failure: AuthenticationFailure & {
+        retryable: false;
+    };
 };
 export interface CredentialField {
     name: string;
@@ -401,6 +416,11 @@ export interface AuthenticationSession {
     complete(request: CompleteAuthenticationRequest): Promise<CompleteAuthenticationResult>;
     /** Cancels an abandoned SSO window or credentials form. */
     cancelAuthentication(flowId: string): Promise<AuthenticationActionResult>;
+    /**
+     * The agent's own Sign out. Tells the provider where it can, deletes the stored secrets whatever
+     * happened, and moves to `signed-out`; answers `failed` when the provider could not be told, so
+     * the host can show that a session may remain there. Never called for a `terminated` session.
+     */
     signOut(): Promise<AuthenticationActionResult>;
     close(): Promise<void>;
 }

package/dist/testing.d.ts

@@ -87,7 +87,7 @@ export declare function assertAuthenticationRestoreAndExpiry(states: readonly Au
  * Capabilities are current, not fixed. A provider that withdraws one republishes `authenticated`
  * with the new set, and the next snapshot agrees with it. `states` is what the authentication
  * session published, first to last: beginning and ending `authenticated` for the same identity,
- * passing only through usable states (`expired` or `signed-out` ends the login instead), with at
+ * passing only through usable states (`expired`, `terminated` or `signed-out` ends the login instead), with at
  * least one capability gone by the end. `snapshot` is the first snapshot published after the last
  * state, validated against that login -- so a team member list still published to a login that no longer
  * leads, or requests to one that may no longer join, is the failure.

package/dist/testing.js

@@ -309,6 +309,17 @@ export async function testAdapter(adapter, context, options = {}) {
             violations.push(...own);
             if (own.length > 0)
                 return;
+            // A session that has ended takes its secrets with it: the adapter deletes them before it
+            // publishes the ending, so a reload has nothing to restore. Only an expiry whose failure is
+            // retryable keeps them, for the retry.
+            if (sessionEnded(state)) {
+                ruleTested("authentication.secrets.retained");
+                if (storedSecrets.size > 0) {
+                    violations.push({ rule: "authentication.secrets.retained", path: "authentication.status",
+                        message: `the session is ${state.status} and the adapter still holds ${storedSecrets.size} stored secret(s): ` +
+                            "an ended session's secrets are deleted before the ending is published, or a reload restores it" });
+                }
+            }
             if (state.status === "refreshing") {
                 violations.push(...refreshingCarriesOver(current(), state, "authentication"));
             }
@@ -904,6 +915,11 @@ export function assertAuthenticationRestoreAndExpiry(states) {
     }
 }
 /** The tasks an envelope carries: the one a task event names, or a snapshot event's list. */
+/** Whether a published state ends the session, so its stored secrets must already be gone. */
+function sessionEnded(state) {
+    return state.status === "signed-out" || state.status === "terminated"
+        || (state.status === "expired" && state.failure?.retryable !== true);
+}
 /** Whether a store key names the task: the id as a delimited token, never as a run of characters inside another id. */
 function namesTask(key, taskId) {
     return key.split(/[^A-Za-z0-9_-]+/).includes(taskId);
@@ -940,7 +956,7 @@ function notYetReadTasks(tasks, path) {
  * Capabilities are current, not fixed. A provider that withdraws one republishes `authenticated`
  * with the new set, and the next snapshot agrees with it. `states` is what the authentication
  * session published, first to last: beginning and ending `authenticated` for the same identity,
- * passing only through usable states (`expired` or `signed-out` ends the login instead), with at
+ * passing only through usable states (`expired`, `terminated` or `signed-out` ends the login instead), with at
  * least one capability gone by the end. `snapshot` is the first snapshot published after the last
  * state, validated against that login -- so a team member list still published to a login that no longer
  * leads, or requests to one that may no longer join, is the failure.

package/dist/validation.js

@@ -49,7 +49,7 @@ const TRANSPORT_STATUSES = membersOf({ connecting: true, active: true, error: tr
 const AUTHENTICATION_METHODS = membersOf({ "browser-sso": true, credentials: true });
 const AUTHENTICATION_BROWSERS = membersOf({ system: true, omni: true });
 const AUTHENTICATION_STATUSES = membersOf({
-    "signed-out": true, authenticating: true, authenticated: true, refreshing: true, expired: true,
+    "signed-out": true, authenticating: true, authenticated: true, refreshing: true, expired: true, terminated: true,
 });
 const BREAK_APPROVALS = membersOf({
     "not-requested": true, "awaiting-approval": true, granted: true, "starting-after-task": true, "on-break": true,
@@ -3131,18 +3131,28 @@ export function validateAuthenticationState(state, path = "authentication", cont
         validateUser(state.identity, "authentication.identity", `${path}.identity`, into);
         validateUserCapabilitiesInto(state.capabilities, `${path}.capabilities`, into, context.levels);
     }
-    else if (state.status === "expired") {
+    else if (state.status === "expired" || state.status === "terminated") {
         if (state.identity !== undefined)
             validateUser(state.identity, "authentication.identity", `${path}.identity`, into);
         if (state.failure !== undefined) {
             validateAuthenticationFailureInto(state.failure, `${path}.failure`, into);
         }
+        if (state.status === "terminated") {
+            // Ended from outside this agent computer: who did it, and why, and nothing to retry.
+            into.require(isUserId(state.by) || state.by === "provider", "authentication.terminated.by", `${path}.by`, "a terminated session says who ended it: the person by user id, or provider where the platform did");
+            if (into.require(isPlainObject(state.failure), "authentication.terminated.failure", `${path}.failure`, "a terminated session carries the reason it was ended")) {
+                into.require(state.failure.retryable === false, "authentication.terminated.retryable", `${path}.failure.retryable`, "a session ended from outside is over: its failure is not retryable");
+            }
+        }
     }
     else {
         into.require(state.identity === undefined, "authentication.identity.unexpected", `${path}.identity`, `${state.status} must not carry an identity`);
     }
     if (state.failure !== undefined) {
-        into.require(state.status === "expired", "authentication.failure.unexpected", `${path}.failure`, "only an expired state may carry a failure");
+        into.require(state.status === "expired" || state.status === "terminated", "authentication.failure.unexpected", `${path}.failure`, "only an expired or terminated state may carry a failure");
+    }
+    if (state.by !== undefined) {
+        into.require(state.status === "terminated", "authentication.by.unexpected", `${path}.by`, "only a terminated session says who ended it; the agent's own sign-out is signed-out");
     }
     if (state.expiresAt !== undefined) {
         into.require(state.status === "authenticated", "authentication.expiresAt.unexpected", `${path}.expiresAt`, "only an authenticated state may carry an expiry");

package/guide/agent.md

@@ -388,6 +388,7 @@ Migration from the earlier spellings:
 | the handset spelled by its place on a desk | `hardphone`, on the manifest's `phones` and the login's `phone`; the former spelling is refused |
 | the desk | the agent computer, in the guide's prose |
 | the agent application's Mute on hold | unavailable while the task is `paused`, promised at login by a softphone login's agent application (`host.guarantees.muteUnavailableOnHold`, required there and refused of a hardphone login); a host mute beginning on a paused task is refused (`historyReport.muted.held`) and the test names an adapter that records one (`test.recordStep.held`) |
+| a session ended from outside the agent computer, reported as `expired` | `terminated`, with `by` (a person or `provider`) and a reason never retryable; `signed-out` is only the agent's own Sign out here; an ended session's secrets are deleted before the ending is published (`authentication.secrets.retained`), kept only for an `expired` whose failure is retryable; the agent application clears the store after, and resumes no stored token |
 
 Update producers, consumers, saved task snapshots, and validation-rule assertions together.
 History and report rule names use `history` and `historyReport`; assignment rules use

package/guide.md

@@ -70,7 +70,7 @@ state use `status`; name the object when discussing them to avoid ambiguity.
 | `phase` | A task | `pending`, `confirmed`, `preview`, `in-progress`, `paused`, `completing` |
 | `audio` | A task's audio | `started`, `ended` |
 | `transport` | A connection | `connecting`, `active`, `error` |
-| `status` | An authentication session | `signed-out`, `authenticating`, `authenticated`, `refreshing`, `expired` |
+| `status` | An authentication session | `signed-out`, `authenticating`, `authenticated`, `refreshing`, `expired`, `terminated` |
 | `status` | The agent’s break lifecycle | `not-requested`, `awaiting-approval`, `granted`, `starting-after-task`, `on-break` |
 | `availability` | A team member | `ready`, `on-task`, `on-break`, `elsewhere`, `signed-out` |
 
@@ -301,7 +301,8 @@ type AuthenticationState =
   | { status: "authenticating" }
   | { status: "authenticated"; identity: User; capabilities: UserCapabilities; expiresAt?: IsoTimestamp }
   | { status: "refreshing"; identity: User; capabilities: UserCapabilities }
-  | { status: "expired"; identity?: User; failure?: AuthenticationFailure };
+  | { status: "expired"; identity?: User; failure?: AuthenticationFailure }
+  | { status: "terminated"; by: UserId | "provider"; identity?: User; failure: AuthenticationFailure & { retryable: false } };
 
 type AuthenticationFailure = {
   code: string;
@@ -1991,11 +1992,12 @@ reports later changes.
 
 | Status | Contract |
 | --- | --- |
-| `signed-out` | No usable provider session exists. |
+| `signed-out` | No usable provider session exists, because the agent signed out on this agent computer, or never signed in. Only the agent's own Sign out here leads to it. |
 | `authenticating` | An interactive `browser-sso` or `credentials` flow is active. |
 | `authenticated` | A usable session exists. Includes the provider identity, the login's `capabilities`, and optional token expiry time. |
 | `refreshing` | The adapter is refreshing its session. Existing provider identity and capabilities remain available, unchanged: a change to either is published as `authenticated`. |
-| `expired` | The session cannot currently be used. It may include an identity and typed failure. |
+| `expired` | The session's time ran out, or its refresh is failing. It may include an identity and typed failure. The agent signs in again on the same login, and the workspace stays. |
+| `terminated` | The session was ended from outside this agent computer: by a supervisor, by the agent on another screen, or by the platform itself. `by` says who, a person by `UserId` or `provider` where no person was behind it (`authentication.terminated.by`), and `failure` says why and is never retryable (`authentication.terminated.failure`, `.retryable`). It is never reported as `expired`, which would hide who ended it, nor as `signed-out`, which is the agent's own act. |
 
 Omni calls `connect()` only after authentication reaches `authenticated`. Token refresh remains
 adapter-owned; the adapter publishes `refreshing`, followed by `authenticated` or `expired`.
@@ -2137,16 +2139,50 @@ authorization codes, tokens, or provider responses containing secrets.
 
 ### Sign-out
 
-`signOut()` revokes or invalidates the provider session where supported, deletes stored
-session secrets, and moves state to `signed-out`.
-`close()` stops authentication-state observation but does not sign the agent out.
+`signOut()` is the agent's own Sign out on this agent computer. It tells the provider where
+supported, revoking or invalidating the session, then **deletes the stored session secrets
+whatever happened**, and moves state to `signed-out`. Telling the provider may be retried within a
+short bound the adapter states, and then given up: a provider that cannot be reached never keeps a
+token on the agent's machine. If it was not told, `signOut()` still deletes and still reaches
+`signed-out`, and answers `failed`, so the agent application can show that a session may remain at
+the provider. `close()` stops authentication-state observation but does not sign the agent out.
+
+**The final moments are the agent application's to finish.** Its own steps before signing out --
+stopping capacity, putting tasks down -- may be retried within a short bound it states, and then
+given up; a step that failed never skips `signOut()`. A desk that skipped the adapter's sign-out
+because its own retirement failed left the token behind, and the next reload restored the session.
+
+### How a session's secrets end
+
+A token that can no longer start a session does not outlive it. The adapter deletes the stored
+secrets **before** it publishes the ending, so that nothing is left for a reload to restore:
+
+| Ending | Secrets | The provider |
+| --- | --- | --- |
+| `signed-out` | Deleted, whether or not the provider was told. | Told where supported, as above. |
+| `terminated` | Deleted. | Never told: the session is already over, and a sign-out sent now could end the agent's newer session somewhere else. |
+| `expired` with a failure that says `retryable: true` | Kept, for the retry: a network outage does not sign out a floor. | Retried by the adapter. |
+| `expired` otherwise | Deleted: the provider refused the token, or its time ran out. | Not told. |
+
+**The agent application makes sure after the adapter.** Once a session is `signed-out`,
+`terminated`, or `expired` with anything but a retryable failure, the agent application clears that
+provider's partition of the store, and a sign-in after it always starts a fresh flow and never
+resumes a stored token. The adapter deletes; the agent application makes sure. `testAdapter` holds
+the adapter's half: when a published state ends the session, the store it handed the adapter must
+already be empty (`authentication.secrets.retained`).
 
 ### Secure-storage boundary
 
-Omni provides an OS-backed `SecretStore` scoped to the provider manifest ID. It exposes only
-`get`, `set`, and `delete`; adapters cannot enumerate another provider's secrets. Adapters may store
-refresh tokens or equivalent session material, but never raw submitted credentials. Secrets must
-not appear in manifests, logs, events, snapshots, task attributes, errors, or browser storage.
+The agent application provides the `SecretStore`, scoped to the provider manifest ID. It exposes
+only `get`, `set`, and `delete`; adapters cannot enumerate another provider's secrets. **What backs
+it is the agent application's, and depends on what it is**: a native agent application uses the
+operating system's keychain; a browser agent application has none, and keeps the store in the
+tab's session storage, which survives a reload and ends with the tab. A browser store is readable
+by any script running on its page, so a browser agent application is only as safe as its own page.
+
+Adapters may store refresh tokens or equivalent session material, but never raw submitted
+credentials, and they put a secret nowhere but the `SecretStore`: never in manifests, logs,
+events, snapshots, task attributes, errors, the login's `store`, or browser storage of their own.
 
 ## Connecting to a provider
 

package/package.json

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