@xemahq/ui-kernel 0.9.1 → 0.10.0

package/src/vista/vista-payloads.ts

@@ -199,7 +199,8 @@ export interface VistaTablePayload {
 export function validateTablePayload(raw: unknown): VistaTablePayload | null {
   const record = asRecord(raw);
   if (record === null) return null;
-  if (!Array.isArray(record.columns) || !Array.isArray(record.rows)) return null;
+  if (!Array.isArray(record.columns) || !Array.isArray(record.rows))
+    return null;
   if (!record.columns.every((c) => typeof c === 'string')) return null;
   if (!record.rows.every((r) => Array.isArray(r))) return null;
   return {
@@ -244,7 +245,8 @@ export function validateChartPayload(raw: unknown): VistaChartPayload | null {
   if (record === null) return null;
   if (typeof record.kind !== 'string' || !CHART_KINDS.includes(record.kind))
     return null;
-  if (typeof record.title !== 'string' || record.title.length === 0) return null;
+  if (typeof record.title !== 'string' || record.title.length === 0)
+    return null;
   if (!Array.isArray(record.series) || record.series.length === 0) return null;
   const series: VistaChartSeries[] = [];
   for (const entry of record.series) {
@@ -377,37 +379,18 @@ export function validateWebPayload(raw: unknown): VistaWebPayload | null {
     : null;
 }
 
-/**
- * An `http(s)` ABSOLUTE URL, or `null`.
- *
- * Every URL on a {@link VistaFormPayload} must be absolute. That is the
- * structural half of "the value goes browser → service and never through the
- * agent": a relative path would resolve against the HOST app's origin — i.e.
- * its BFF, where the chat transport lives — so a relative submit target is
- * rejected outright rather than normalised.
- */
-function absoluteHttpUrl(value: unknown): string | null {
-  if (typeof value !== 'string' || value.length === 0) return null;
-  let parsed: URL;
-  try {
-    parsed = new URL(value);
-  } catch {
-    return null;
-  }
-  return parsed.protocol === 'https:' || parsed.protocol === 'http:' ? value : null;
-}
-
 /**
  * The consent / install handoff of a {@link VistaFormPayload}.
  *
  * Present when the connector's app auth is `oauth2` or `app_install`: there is
  * no field form to fill, only a link the user follows in another window. It is
- * fully generic — the URL is minted per-provider by the owning service and
- * carried here verbatim, so no provider is special-cased in the renderer.
+ * fully generic — the owning service supplies a path under the host-configured
+ * trusted service origin, so no provider is special-cased in the renderer and
+ * an agent-controlled payload never selects a network authority.
  */
 export interface VistaFormLaunch {
-  /** ABSOLUTE consent / install URL, opened in a new window. */
-  readonly url: string;
+  /** Root-relative consent / install path on the trusted elicitation service. */
+  readonly path: string;
   /** Button copy, e.g. "Install Acme" / "Continue to Acme". */
   readonly label: string;
   /** Optional explanation rendered above the button. */
@@ -421,10 +404,10 @@ export interface VistaFormLaunch {
  * never see. Two mutually-exclusive modes, chosen by the presence of
  * {@link launch}:
  *
- *   • FIELD mode — render `fields`, POST them to `submitUrl` with the user's
- *     own JWT;
+ *   • FIELD mode — render `fields`, POST them through the host's trusted
+ *     elicitation-service base URL with the user's own JWT;
  *   • LAUNCH mode — render the consent/install link, then confirm completion
- *     against `statusUrl`.
+ *     through that same trusted service.
  *
  * Both settle into the same `{ submitted, ref }` shape, so the agent's view of
  * the world does not depend on which mode ran.
@@ -434,10 +417,6 @@ export interface VistaFormPayload {
   readonly ref: string;
   /** Why the credential is being asked for — shown to the user verbatim. */
   readonly purpose: string;
-  /** ABSOLUTE service URL the captured fields are POSTed to. */
-  readonly submitUrl: string;
-  /** ABSOLUTE service URL reporting whether the elicitation has settled. */
-  readonly statusUrl: string;
   /** The onboarding form's fields. MAY be empty — the service is the authority. */
   readonly fields: readonly CaptureFieldSpec[];
   /** Optional heading override (defaults to the tab title). */
@@ -448,16 +427,26 @@ export interface VistaFormPayload {
   readonly launch?: VistaFormLaunch;
 }
 
+const VISTA_FORM_REF_PATTERN = /^[A-Za-z0-9_-]{1,256}$/;
+
+/** Whether a value is one opaque base64url elicitation path segment. */
+export function isValidVistaFormRef(value: unknown): value is string {
+  return typeof value === 'string' && VISTA_FORM_REF_PATTERN.test(value);
+}
+
 export function validateFormPayload(raw: unknown): VistaFormPayload | null {
   const record = asRecord(raw);
   if (record === null) return null;
-  if (typeof record.ref !== 'string' || record.ref.length === 0) return null;
+  // The service generates base64url refs. Keeping the accepted alphabet closed
+  // makes the ref safe as exactly one URL path segment; dot segments, slashes,
+  // percent escapes and Unicode lookalikes are all rejected.
+  if (!isValidVistaFormRef(record.ref)) {
+    return null;
+  }
   if (typeof record.purpose !== 'string') return null;
-
-  const submitUrl = absoluteHttpUrl(record.submitUrl);
-  if (submitUrl === null) return null;
-  const statusUrl = absoluteHttpUrl(record.statusUrl);
-  if (statusUrl === null) return null;
+  // Deliberately reject the old contract rather than silently ignoring its
+  // payload-selected network targets.
+  if ('submitUrl' in record || 'statusUrl' in record) return null;
 
   const fields = validateCaptureFields(record.fields);
   if (fields === null) return null;
@@ -471,24 +460,32 @@ export function validateFormPayload(raw: unknown): VistaFormPayload | null {
   if (record.launch !== undefined) {
     const raw_ = asRecord(record.launch);
     if (raw_ === null) return null;
-    const url = absoluteHttpUrl(raw_.url);
-    if (url === null) return null;
+    if ('url' in raw_) return null;
+    if (
+      typeof raw_.path !== 'string' ||
+      !raw_.path.startsWith('/') ||
+      raw_.path.startsWith('//') ||
+      raw_.path.includes('\\')
+    ) {
+      return null;
+    }
     if (typeof raw_.label !== 'string' || raw_.label.length === 0) return null;
     const hint = optionalString(raw_.hint);
     if (hint === null) return null;
-    launch = hint === undefined ? { url, label: raw_.label } : { url, label: raw_.label, hint };
+    launch =
+      hint === undefined
+        ? { path: raw_.path, label: raw_.label }
+        : { path: raw_.path, label: raw_.label, hint };
   }
 
   const payload: {
     ref: string;
     purpose: string;
-    submitUrl: string;
-    statusUrl: string;
     fields: readonly CaptureFieldSpec[];
     heading?: string;
     submitLabel?: string;
     launch?: VistaFormLaunch;
-  } = { ref: record.ref, purpose: record.purpose, submitUrl, statusUrl, fields };
+  } = { ref: record.ref, purpose: record.purpose, fields };
   if (heading !== undefined) payload.heading = heading;
   if (submitLabel !== undefined) payload.submitLabel = submitLabel;
   if (launch !== undefined) payload.launch = launch;
@@ -505,7 +502,8 @@ export interface VistaAppPayload {
 export function validateAppPayload(raw: unknown): VistaAppPayload | null {
   const record = asRecord(raw);
   if (record === null) return null;
-  if (typeof record.appId !== 'string' || record.appId.length === 0) return null;
+  if (typeof record.appId !== 'string' || record.appId.length === 0)
+    return null;
   const path = optionalString(record.path);
   if (path === null) return null;
   return path === undefined

package/src/vista/vista-tools.ts

@@ -120,7 +120,7 @@ export const VistaToolResultSchema: z.ZodType<VistaToolResult> = z.union([
     error: z.nativeEnum(VistaToolError),
     detail: z.string().optional(),
   }),
-]) as z.ZodType<VistaToolResult>;
+]);
 
 /**
  * Perform a relayed Vista tool call against a mounted panel's controller.
@@ -151,7 +151,7 @@ export function dispatchVistaTool(
       const { tabId, ...patch } = parsed.data;
       const refusal = refusalFor(controller, tabId);
       if (refusal !== null) return refusal;
-      if (!controller.update(tabId, patch as VistaSurfacePatch)) {
+      if (!controller.update(tabId, patch)) {
         // The tab is listed but not opened-tab-owned: it is a HOST tab, and a
         // patch to it would be overwritten by the host's next reconcile.
         return {

package/dist/lib/biome-host/response-envelope.d.ts

@@ -1,3 +0,0 @@
-export declare function unwrapList<T>(value: unknown): T[];
-export declare function unwrapData<T>(value: unknown): T;
-//# sourceMappingURL=response-envelope.d.ts.map

package/dist/lib/biome-host/response-envelope.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"response-envelope.d.ts","sourceRoot":"","sources":["../../../src/lib/biome-host/response-envelope.ts"],"names":[],"mappings":"AA+BA,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,EAAE,CAYjD;AAeD,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAU/C"}

package/dist/lib/biome-host/response-envelope.js

@@ -1,21 +0,0 @@
-export function unwrapList(value) {
-    if (Array.isArray(value)) {
-        return value;
-    }
-    if (value !== null &&
-        typeof value === 'object' &&
-        Array.isArray(value.data)) {
-        return value.data;
-    }
-    return [];
-}
-export function unwrapData(value) {
-    if (value !== null &&
-        typeof value === 'object' &&
-        'data' in value &&
-        !('pagination' in value)) {
-        return value.data;
-    }
-    return value;
-}
-//# sourceMappingURL=response-envelope.js.map

package/dist/lib/biome-host/response-envelope.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"response-envelope.js","sourceRoot":"","sources":["../../../src/lib/biome-host/response-envelope.ts"],"names":[],"mappings":"AA+BA,MAAM,UAAU,UAAU,CAAI,KAAc;IAC1C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAY,CAAC;IACtB,CAAC;IACD,IACE,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,CAAC,OAAO,CAAE,KAA4B,CAAC,IAAI,CAAC,EACjD,CAAC;QACD,OAAQ,KAAuB,CAAC,IAAI,CAAC;IACvC,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAeD,MAAM,UAAU,UAAU,CAAI,KAAc;IAC1C,IACE,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,MAAM,IAAK,KAAiC;QAC5C,CAAC,CAAC,YAAY,IAAK,KAAiC,CAAC,EACrD,CAAC;QACD,OAAQ,KAAqB,CAAC,IAAI,CAAC;IACrC,CAAC;IACD,OAAO,KAAU,CAAC;AACpB,CAAC"}

package/dist/lib/biome-host/session-profiles.d.ts

@@ -1,18 +0,0 @@
-export declare const SessionCapabilities: {
-    readonly HasGit: "hasGit";
-    readonly HasWorkspaceFiles: "hasWorkspaceFiles";
-    readonly SupportsKbPush: "supportsKbPush";
-    readonly HasArtifacts: "hasArtifacts";
-    readonly SupportsForking: "supportsForking";
-    readonly SupportsSharing: "supportsSharing";
-};
-export type SessionCapability = (typeof SessionCapabilities)[keyof typeof SessionCapabilities];
-export interface SessionProfileDescriptor {
-    readonly key: string;
-    readonly biomeId: string;
-    readonly label: string;
-    readonly description?: string;
-    readonly capabilities: readonly string[];
-}
-export declare function useSessionProfileDescriptor(biomeId: string | undefined, profileKey: string | undefined): SessionProfileDescriptor;
-//# sourceMappingURL=session-profiles.d.ts.map

package/dist/lib/biome-host/session-profiles.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"session-profiles.d.ts","sourceRoot":"","sources":["../../../src/lib/biome-host/session-profiles.ts"],"names":[],"mappings":"AA6BA,eAAO,MAAM,mBAAmB;;;;;;;CAatB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAC3B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAEjE,MAAM,WAAW,wBAAwB;IAKvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAcD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,wBAAwB,CAqB1B"}

package/dist/lib/biome-host/session-profiles.js

@@ -1,35 +0,0 @@
-import { useMemo } from 'react';
-import { biomeRegistry, useBiomeRegistryRevision } from './biome-registry';
-export const SessionCapabilities = {
-    HasGit: 'hasGit',
-    HasWorkspaceFiles: 'hasWorkspaceFiles',
-    SupportsKbPush: 'supportsKbPush',
-    HasArtifacts: 'hasArtifacts',
-    SupportsForking: 'supportsForking',
-    SupportsSharing: 'supportsSharing',
-};
-export function useSessionProfileDescriptor(biomeId, profileKey) {
-    const revision = useBiomeRegistryRevision();
-    return useMemo(() => {
-        const fallback = {
-            key: profileKey ?? 'unknown',
-            biomeId: biomeId ?? 'unknown',
-            label: profileKey ?? 'Unknown profile',
-            capabilities: [],
-        };
-        if (!profileKey)
-            return fallback;
-        let crossPluginMatch;
-        for (const biome of biomeRegistry.list()) {
-            for (const profile of biome.session?.profiles ?? []) {
-                if (profile.key !== profileKey)
-                    continue;
-                if (biomeId != null && profile.biomeId === biomeId)
-                    return profile;
-                crossPluginMatch ??= profile;
-            }
-        }
-        return crossPluginMatch ?? fallback;
-    }, [revision, biomeId, profileKey]);
-}
-//# sourceMappingURL=session-profiles.js.map

package/dist/lib/biome-host/session-profiles.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"session-profiles.js","sourceRoot":"","sources":["../../../src/lib/biome-host/session-profiles.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAEhC,OAAO,EAAE,aAAa,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAU3E,MAAM,CAAC,MAAM,mBAAmB,GAAG;IAEjC,MAAM,EAAE,QAAQ;IAEhB,iBAAiB,EAAE,mBAAmB;IAEtC,cAAc,EAAE,gBAAgB;IAEhC,YAAY,EAAE,cAAc;IAE5B,eAAe,EAAE,iBAAiB;IAElC,eAAe,EAAE,iBAAiB;CAC1B,CAAC;AAgCX,MAAM,UAAU,2BAA2B,CACzC,OAA2B,EAC3B,UAA8B;IAE9B,MAAM,QAAQ,GAAG,wBAAwB,EAAE,CAAC;IAC5C,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,QAAQ,GAA6B;YACzC,GAAG,EAAE,UAAU,IAAI,SAAS;YAC5B,OAAO,EAAE,OAAO,IAAI,SAAS;YAC7B,KAAK,EAAE,UAAU,IAAI,iBAAiB;YACtC,YAAY,EAAE,EAAE;SACjB,CAAC;QACF,IAAI,CAAC,UAAU;YAAE,OAAO,QAAQ,CAAC;QACjC,IAAI,gBAAsD,CAAC;QAC3D,KAAK,MAAM,KAAK,IAAI,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC;YACzC,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,CAAC;gBACpD,IAAI,OAAO,CAAC,GAAG,KAAK,UAAU;oBAAE,SAAS;gBACzC,IAAI,OAAO,IAAI,IAAI,IAAI,OAAO,CAAC,OAAO,KAAK,OAAO;oBAAE,OAAO,OAAO,CAAC;gBACnE,gBAAgB,KAAK,OAAO,CAAC;YAC/B,CAAC;QACH,CAAC;QACD,OAAO,gBAAgB,IAAI,QAAQ,CAAC;IAEtC,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;AACtC,CAAC"}

package/src/lib/biome-host/response-envelope.ts

@@ -1,69 +0,0 @@
-/**
- * Frontend mirror of the backend `ResponseEnvelopeInterceptor`.
- *
- * Every 2xx body the platform returns is wrapped as `{ data: T }`, or
- * `{ data: T[], pagination }` for a paginated list (single source of truth:
- * `@xemahq/platform-common`'s `ResponseEnvelopeInterceptor`). Orval's
- * `custom-fetch` mutators usually peel that envelope at the HTTP boundary, but
- * spec drift (a controller typed `T[]` that emits `{ data }`), public clients
- * that DON'T peel, and transient partial responses leave a `.data`-wrapped or
- * mis-shaped value where biome code expects a bare value/array — and a raw
- * `.map` on it white-screens the route.
- *
- * These are the ONE shared, pure unwrap helpers — no host context, no fetch.
- * Biomes (and the host shell's own `unwrap-list.ts`) should adopt these instead
- * of re-implementing the guard. This is the shared helper only; adopters are
- * migrated incrementally, not in a blanket rewrite.
- */
-
-/**
- * Resilient list unwrap for DISPLAY surfaces — normalises a React-Query `.data`
- * to an array so the page renders its empty/error state instead of crashing:
- *
- *   - already an array        → returned as-is
- *   - `{ data: T[] }` envelope → `value.data`
- *   - anything else            → `[]`
- *
- * Deliberately NON-throwing: the query's own `isError`/`isLoading` flags drive
- * the visible error/empty UI; this only guards the render path. For
- * mutation/single-resource flows where an unexpected shape is a real bug, use
- * {@link unwrapData} (fail-fast) instead.
- */
-export function unwrapList<T>(value: unknown): T[] {
-  if (Array.isArray(value)) {
-    return value as T[];
-  }
-  if (
-    value !== null &&
-    typeof value === 'object' &&
-    Array.isArray((value as { data?: unknown }).data)
-  ) {
-    return (value as { data: T[] }).data;
-  }
-  return [];
-}
-
-/**
- * Fail-fast single-resource unwrap. Returns `value.data` when the value is a
- * `{ data }` envelope; returns the value unchanged when it is already the
- * unwrapped resource (an Orval client that peeled the envelope at the boundary).
- *
- * Use this on mutation / single-resource flows where the response SHOULD be a
- * concrete object — unlike {@link unwrapList}, it does not silently coerce, so
- * a genuinely-unexpected shape surfaces as the value rather than being masked.
- *
- * A paginated envelope (`{ data, pagination }`) is returned INTACT — callers
- * that need both fields read them off the returned object; peeling only `data`
- * would drop the pagination cursor.
- */
-export function unwrapData<T>(value: unknown): T {
-  if (
-    value !== null &&
-    typeof value === 'object' &&
-    'data' in (value as Record<string, unknown>) &&
-    !('pagination' in (value as Record<string, unknown>))
-  ) {
-    return (value as { data: T }).data;
-  }
-  return value as T;
-}

package/src/lib/biome-host/session-profiles.ts

@@ -1,99 +0,0 @@
-/**
- * Session profile descriptors — coarse capability flags that gate which
- * UI surfaces a session shows. A profile is owned by exactly one biome
- * (matched by `(biomeId, key)`) and declares a set of namespaced
- * capability strings the host fans out as `SessionContext.capabilities`.
- *
- * Biomes consume capabilities through each contribution's `appliesTo`
- * predicate — the host shell itself never branches on a capability
- * string. This keeps the host neutral; a session that doesn't declare
- * `hasGit` simply gets no git-touching contributions because every git
- * contribution gates on `ctx.capabilities.has('hasGit')`.
- *
- * Capability namespacing: well-known capabilities are documented here as
- * constants so first-party biomes agree on a vocabulary; third-party
- * biomes MUST namespace their own capabilities (`<biome-id>:<flag>`)
- * to avoid collisions.
- */
-import { useMemo } from 'react';
-
-import { biomeRegistry, useBiomeRegistryRevision } from './biome-registry';
-
-/**
- * Well-known capability flags first-party biomes share. Third-party
- * biomes SHOULD prefer namespacing their own (`<biome-id>:<flag>`).
- *
- * Adding a constant here is a contract-stability statement — it
- * documents a flag enough first-party biomes use that we want a stable
- * spelling. Removing one is a breaking change.
- */
-export const SessionCapabilities = {
-  /** Session backs a git workspace; branches, commits, push, PR. */
-  HasGit: 'hasGit',
-  /** Session emits workspace file mutations (created/edited/deleted). */
-  HasWorkspaceFiles: 'hasWorkspaceFiles',
-  /** Session can publish artefacts back to the knowledge base. */
-  SupportsKbPush: 'supportsKbPush',
-  /** Session can open / render in-workspace artefacts (apps, docs). */
-  HasArtifacts: 'hasArtifacts',
-  /** Session can fork to a new branch. */
-  SupportsForking: 'supportsForking',
-  /** Session can share its output (deliverable) to other surfaces. */
-  SupportsSharing: 'supportsSharing',
-} as const;
-
-export type SessionCapability =
-  (typeof SessionCapabilities)[keyof typeof SessionCapabilities];
-
-export interface SessionProfileDescriptor {
-  /**
-   * Stable profile key — matches the backend's `Session.profileKey`
-   * (or the session manifest slug for newer profiles).
-   */
-  readonly key: string;
-  /** Biome that owns this profile. */
-  readonly biomeId: string;
-  /** Displayed label. */
-  readonly label: string;
-  readonly description?: string;
-  /** Capability flags the host fans out as `SessionContext.capabilities`. */
-  readonly capabilities: readonly string[];
-}
-
-/**
- * Hook returning the descriptor that matches a session's `(biomeId,
- * profileKey)`. Falls back to a synthetic descriptor with the well-known
- * core capabilities when no biome owns the profile — that's how
- * sessions started before any biome loaded still get usable defaults
- * (today's behaviour).
- *
- * Resolution order:
- *   1. Exact match on `(biomeId, key)`.
- *   2. Exact match on `key` alone (cross-biome profile name).
- *   3. Synthetic fallback (`unknown` biome, empty capabilities).
- */
-export function useSessionProfileDescriptor(
-  biomeId: string | undefined,
-  profileKey: string | undefined,
-): SessionProfileDescriptor {
-  const revision = useBiomeRegistryRevision();
-  return useMemo(() => {
-    const fallback: SessionProfileDescriptor = {
-      key: profileKey ?? 'unknown',
-      biomeId: biomeId ?? 'unknown',
-      label: profileKey ?? 'Unknown profile',
-      capabilities: [],
-    };
-    if (!profileKey) return fallback;
-    let crossPluginMatch: SessionProfileDescriptor | undefined;
-    for (const biome of biomeRegistry.list()) {
-      for (const profile of biome.session?.profiles ?? []) {
-        if (profile.key !== profileKey) continue;
-        if (biomeId != null && profile.biomeId === biomeId) return profile;
-        crossPluginMatch ??= profile;
-      }
-    }
-    return crossPluginMatch ?? fallback;
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [revision, biomeId, profileKey]);
-}