@xema/omni-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vasu Inukollu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# Omni-Protocol
+
+The contract every provider adapter implements, and the checks that hold adapters to it.
+
+A provider is one independently connected external system — a voice platform, a chat platform, a
+mail platform. An adapter is the package speaking this contract for one provider. Omni composes
+several providers into one agent-facing desktop and owns everything outside a provider's own
+system.
+
+## What is here
+
+| Path | |
+| --- | --- |
+| `guide.md` | **The protocol.** Rules, shapes, and the reasoning behind them. |
+| `src/index.ts` | The TypeScript declarations. |
+| `src/validation.ts` | Runtime validators Omni applies to adapter output. |
+| `src/testing.ts` | Conformance helpers an adapter runs against its own test state. |
+
+## Entry points
+
+```ts
+import { defineAdapter } from "@xema/omni-protocol";
+import { validateSnapshot, assertNoViolations } from "@xema/omni-protocol/validation";
+import { exerciseAdapter } from "@xema/omni-protocol/testing";
+```
+
+## Validation is not only for tests
+
+An adapter is loaded from a separate package and may be compiled against a different protocol
+version, so its output is untrusted input. Every validator takes `unknown` and returns every
+violation it found rather than throwing on the first, so a caller reports all of them at once.
+Validating a snapshot before it replaces provider state is what stops a malformed task reaching
+the agent's workspace.
+
+```ts
+const violations = validateSnapshot(snapshot, manifest);
+assertNoViolations(violations);
+```
+
+A violation carries a stable `rule` id such as `task.browser.url.scheme`, the `path` it was found
+at such as `snapshot.tasks[0].browsers[1].url`, and a `message`.
+
+## Conformance
+
+`exerciseAdapter` validates the manifest, opens an authenticated session, connects, checks
+required capability methods, subscribes, validates the snapshot and every delivered event, states
+a capacity, then unsubscribes and disconnects.
+
+```ts
+const result = await exerciseAdapter(adapter, context, { collectOnly: true });
+expect(result.violations).toEqual([]);
+expect(result.disconnectWasClean).toBe(true);
+```
+
+Run the contract scenarios beside it — authentication restore and expiry, reconnect with missed
+assignments, break denial and retry, command idempotency, wrap timeout, browser isolation.
+
+> **Assert both directions.** Every helper rejects a violating input as well as accepting a
+> conforming one. A suite that only asserts "this conforming case does not throw" passes unchanged
+> if the helper is gutted, so pair every positive case with the violating twin.
+
+## Building
+
+```
+pnpm install
+pnpm build        # emits dist/
+pnpm test         # type-checks the tests, then runs them
+```
+
+## The guide is authoritative
+
+Where `guide.md` and any code here disagree, the guide is right and the code is a defect. It has
+been through review and is not edited casually.

package/dist/design.d.ts

@@ -0,0 +1,49 @@
+export type ThemePreference = "system" | "light" | "dark";
+export type ResolvedTheme = Exclude<ThemePreference, "system">;
+export type Density = "compact" | "comfortable" | "spacious";
+/** Semantic values consumed by Omni's layout, independent of a CSS framework. */
+export interface DesignTokens {
+    accent: string;
+    accentText: string;
+    surface: string;
+    surfaceMuted: string;
+    selected: string;
+    text: string;
+    mutedText: string;
+    border: string;
+    info: string;
+    success: string;
+    warning: string;
+    danger: string;
+    radius: string;
+    radiusLarge: string;
+    shadow: string;
+    controlFont: string;
+    controlWeight: string;
+    controlTracking: string;
+    controlHeight: string;
+}
+export type ControlKind = "button" | "icon-button" | "checkbox" | "input" | "textarea" | "select" | "tabs" | "menu" | "badge" | "card" | "progress";
+export interface DesignLanguageManifest {
+    id: string;
+    displayName: string;
+    supportedThemes: ReadonlyArray<ResolvedTheme>;
+    supportedControls: ReadonlyArray<ControlKind>;
+    defaultDensity: Density;
+}
+export interface DesignLanguage {
+    manifest: DesignLanguageManifest;
+    tokens: Record<ResolvedTheme, DesignTokens>;
+}
+/**
+ * A framework bridge can use any native control representation: an Angular
+ * component type, a React component, or an Omni DOM renderer. The protocol
+ * deliberately does not make one UI framework part of the ABI.
+ */
+export interface DesignLanguageAdapter<TControl = unknown> {
+    readonly language: DesignLanguage;
+    resolveControl(kind: ControlKind): TControl | Promise<TControl>;
+}
+export declare function defineDesignLanguage<TControl, T extends DesignLanguageAdapter<TControl>>(adapter: T): T;
+/** Maps semantic tokens to the stable CSS custom properties understood by Omni. */
+export declare function designTokenProperties(tokens: DesignTokens): Record<string, string>;

package/dist/design.js

@@ -0,0 +1,27 @@
+export function defineDesignLanguage(adapter) {
+    return adapter;
+}
+/** Maps semantic tokens to the stable CSS custom properties understood by Omni. */
+export function designTokenProperties(tokens) {
+    return {
+        "--omni-accent": tokens.accent,
+        "--omni-accent-text": tokens.accentText,
+        "--omni-surface": tokens.surface,
+        "--omni-surface-muted": tokens.surfaceMuted,
+        "--omni-selected": tokens.selected,
+        "--omni-text": tokens.text,
+        "--omni-muted-text": tokens.mutedText,
+        "--omni-border": tokens.border,
+        "--omni-info": tokens.info,
+        "--omni-success": tokens.success,
+        "--omni-warning": tokens.warning,
+        "--omni-danger": tokens.danger,
+        "--omni-radius": tokens.radius,
+        "--omni-radius-large": tokens.radiusLarge,
+        "--omni-shadow": tokens.shadow,
+        "--omni-control-font": tokens.controlFont,
+        "--omni-control-weight": tokens.controlWeight,
+        "--omni-control-tracking": tokens.controlTracking,
+        "--omni-control-height": tokens.controlHeight,
+    };
+}