@xemahq/ui-kernel 0.11.1 → 0.12.0

package/src/lib/biome-host/realtime-port.ts

@@ -1,115 +0,0 @@
-/**
- * Host-agnostic realtime (CloudEvents over SSE) port.
- *
- * Frontend biomes need to subscribe to server-pushed CloudEvents (session
- * lifecycle, tool calls, notifications, …). The transport — the unified SSE
- * connection, the Keycloak-minted bearer, the active-org header, cross-tab
- * leader election, server-side scope subscriptions — is HOST-owned (today
- * `@xemahq/realtime-client` wrapped by the host's `RealtimeProvider`). Biomes
- * must NOT import that client or `EventSource` directly, exactly as they must
- * not import `next/navigation` or `sonner`.
- *
- * Instead the host injects a concrete {@link RealtimeSource} when it builds the
- * {@link HostBridge}; it is hung off `bridge.realtime`. Biomes reach it through
- * the {@link useCloudEvent} / {@link useRealtimeStatus} / {@link useEventScope}
- * kernel hooks — the same decoupling pattern as `bridge.navigation` /
- * `bridge.capabilities`.
- *
- * Framework-agnostic: pure interface contracts, no React, no SSE, no fetch.
- */
-
-/**
- * The subset of the CloudEvents-shape envelope a biome handler receives.
- *
- * Locally typed in the kernel (deliberately NOT imported from
- * `@xemahq/realtime-client` / `@xemahq/events`) so `@xemahq/ui-kernel` stays
- * transport-free and host-agnostic. The host's realtime client emits an object
- * that is structurally assignable to this — value-identical to the client's
- * `DeliveredEvent`, kept here as the kernel's stable contract.
- */
-export interface RealtimeCloudEvent {
-  /** CloudEvents `id` — unique per delivered event, when the server stamps it. */
-  id?: string;
-  /** CloudEvents `type`, e.g. `session.lifecycle.changed`. The subscription key. */
-  type: string;
-  /** CloudEvents `source`, e.g. `/services/activity-feed-api` or `/biomes/<id>`. */
-  source?: string;
-  /** CloudEvents `subject`, e.g. `session/<session-id>`. */
-  subject?: string;
-  /** CloudEvents `data` payload. Biomes narrow this themselves. */
-  data?: unknown;
-  /** Org-id header echoed onto every delivered envelope. */
-  ehorgid: string;
-  /** Project-id header, when the event is project-scoped. */
-  ehprojectid?: string;
-  /** User-id header, when the event is user-scoped. */
-  ehuserid?: string;
-  /** Global delivery cursor. */
-  ehglobalseq?: string;
-  /** Per-org delivery cursor. */
-  ehorgseq?: string;
-  /** Per-project delivery cursor. */
-  ehprojectseq?: string;
-  /** Per-session delivery cursor. */
-  ehsessionseq?: string;
-  /** Frontend-only invalidation hint carried alongside the envelope. */
-  __hint?: unknown;
-}
-
-/** Coarse realtime connection status for status indicators. */
-export type RealtimeStatus =
-  | 'idle'
-  | 'connecting'
-  | 'connected'
-  | 'reconnecting'
-  | 'closed';
-
-/** Coarse connection state surfaced to status UIs. */
-export interface RealtimeConnectionState {
-  readonly status: RealtimeStatus;
-  /** Latest connectionId returned by the upstream `CONNECTED` frame. */
-  readonly connectionId?: string;
-}
-
-/**
- * A server-side scope a connection can subscribe to so it only receives the
- * events for one project, session, or app, rather than the full org firehose.
- * The host's transport reference-counts identical scopes across mounts.
- *
- * `app` is the app-surface scope: an external/app-facing biome subscribes to
- * its app's event stream (delivery is authz-gated server-side by the subject's
- * app membership). It is value-identical to the server `ScopeKind.app` and the
- * host transport's `EventScopeOptions` — the kernel union is the last hop to
- * carry it, so a decoupled/remote biome can type an app subscription.
- */
-export interface RealtimeScope {
-  readonly kind: 'project' | 'session' | 'app';
-  readonly id: string;
-}
-
-/**
- * Host-implemented realtime source. The host wires each method against its
- * realtime transport (`@xemahq/realtime-client`'s `RealtimeContext`) and passes
- * it in when building the {@link HostBridge}.
- *
- * Every method is a React hook (it reads transport context / state), so it
- * MUST be called from a biome component's render — the kernel `useCloudEvent` /
- * `useRealtimeStatus` / `useEventScope` hooks delegate straight through.
- */
-export interface RealtimeSource {
-  /**
-   * Subscribe `handler` to every delivered CloudEvent whose `type` matches
-   * `eventType`, for the lifetime of the calling component. Per-`data` filtering
-   * (e.g. by `sessionId`) is the handler's responsibility. Mirrors the host
-   * client's `useCloudEvent`.
-   */
-  useCloudEvent(eventType: string, handler: (event: RealtimeCloudEvent) => void): void;
-  /** Coarse connection state for a status indicator. */
-  useRealtimeStatus(): RealtimeConnectionState;
-  /**
-   * Subscribe the connection's unified SSE to a project/session scope while the
-   * calling component is mounted; auto-unsubscribes on unmount. Server-side
-   * subscriptions are reference-counted by the host transport.
-   */
-  useEventScope(scope: RealtimeScope): void;
-}

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

@@ -1,296 +0,0 @@
-/**
- * Declarative session contribution types — every UI extension a frontend
- * biome can drop into the agent-session shell. The host shell
- * carries generic primitives; the registries declared here are how
- * biomes (first-party or third-party) hook those primitives into a
- * concrete user experience.
- *
- * Contract shape: each contribution is a small data object the biome
- * adds to its `FrontendBiome.session.*` field. The host's session
- * components call typed selector hooks (`useSessionSlashCommands`,
- * `useSessionDrawerTabs`, …) which walk the biome registry and return
- * the contributions whose `appliesTo` predicate passes for the current
- * `SessionContext`.
- *
- * `appliesTo` is the single gating primitive — biomes use it to scope
- * a contribution to explicit Agent, workspace, domain, or session status
- * facts. Without it, every contribution applies everywhere.
- *
- * Naming convention: contribution ids MUST be namespaced as
- * `<biome-id>/<contribution>` so cross-biome collisions surface
- * deterministically at registration time (`RegistryDuplicateKeyError`).
- */
-import type { HostBridge } from './host-bridge';
-import type { ComponentType, ReactNode } from 'react';
-
-/**
- * Read-only snapshot of the session the contribution is evaluated
- * against. Passed into every `appliesTo` predicate and every render
- * function so contributions can adapt without subscribing to the host's
- * query cache themselves.
- */
-export interface SessionContext {
-  readonly sessionId: string;
-  readonly orgId: string;
-  readonly projectId: string;
-  /**
-   * Biome id that owns the session's profile (e.g. `'software-dev'`,
-   * `'design-system-builder'`). Biomes use this to filter contributions to
-   * sessions they care about.
-   */
-  readonly biomeId?: string;
-  readonly status: string;
-  /**
-   * The resolved Agent contract that launched this session. This is
-   * runtime truth returned by the Agent resolver, never a UI-authored
-   * profile or a synthetic fallback.
-   */
-  readonly agent?: SessionResolvedAgent;
-  /** Repository actually bound to the session, when one exists. */
-  readonly repositoryId?: string;
-  /**
-   * `true` while the session is in a state that accepts new work
-   * (running, waiting, idle); `false` for terminal/paused/failed states.
-   * Mirrors the legacy `isActive` boolean the host shell already passes
-   * around so contributions can disable destructive actions.
-   */
-  readonly isActive: boolean;
-}
-
-/**
- * UI-safe projection of the resolved Agent contract. The host obtains this
- * from the Agent resolver and passes it into the kernel; plugins only consume
- * the explicit permission/workspace facts they need.
- */
-export interface SessionResolvedAgent {
-  readonly ref: string;
-  readonly requiredCapabilities: ReadonlySet<string>;
-  readonly mayEditRepositories: boolean;
-  readonly mayWriteKnowledgeBase: boolean;
-  readonly hasOutputSurface: boolean;
-}
-
-/**
- * Stable representation of a session console event passed into activity
- * + tool-call renderers. Mirrors the host's `SessionConsoleEntry` minus
- * host-specific fields — renderers should not depend on host internals.
- */
-export interface SessionActivityEvent {
-  readonly id: string;
-  readonly kind: string;
-  readonly sequence?: number;
-  readonly createdAt: string;
-  readonly title: string;
-  readonly content?: string;
-  readonly detail?: string;
-  readonly status?: 'pending' | 'completed' | 'error';
-  readonly payload?: Record<string, unknown>;
-}
-
-/**
- * Stable representation of a tool-call event passed into tool-call
- * renderers. `name` is the tool's canonical id (e.g. `'bash_run'`,
- * `'jira.create_issue'`); biomes MAY use namespaced names so their
- * renderers don't collide with other biomes'.
- */
-export interface SessionToolCallEvent {
-  readonly id: string;
-  readonly name: string;
-  readonly status: 'pending' | 'completed' | 'error';
-  readonly startedAt: string;
-  readonly completedAt?: string;
-  readonly args?: Record<string, unknown>;
-  readonly result?: unknown;
-  readonly error?: string;
-}
-
-// ── Slash commands ─────────────────────────────────────────────────────
-
-export interface SlashCommandContext {
-  readonly session: SessionContext;
-  readonly bridge: HostBridge;
-}
-
-export interface SlashCommandContribution {
-  /** Namespaced id (`<biome-id>/<name>`). */
-  readonly id: string;
-  /** Command keyword users type after `/` (no slash; e.g. `'commit'`). */
-  readonly name: string;
-  /** Displayed label in the autocomplete popup. */
-  readonly label: string;
-  readonly description: string;
-  readonly icon?: ComponentType<{ className?: string | undefined }>;
-  /** Sort weight inside the autocomplete list (lower first; default 100). */
-  readonly weight?: number;
-  /** Hide the command unless the session matches. */
-  readonly appliesTo?: (ctx: SessionContext) => boolean;
-  /** Disable the command when the session is paused/terminal. */
-  readonly requiresActiveSession?: boolean;
-  /** Invoked when the user selects the command. */
-  readonly onSelect: (ctx: SlashCommandContext) => void | Promise<void>;
-}
-
-// ── Secondary drawer tabs ─────────────────────────────────────────────
-
-export interface SecondaryDrawerTabContext {
-  readonly session: SessionContext;
-  readonly bridge: HostBridge;
-}
-
-export interface SecondaryDrawerTabContribution {
-  /** Namespaced id (`<biome-id>/<tab>`). */
-  readonly id: string;
-  /** Stable short key used by keyboard shortcuts (`'tools'`, `'git'`, …). */
-  readonly key: string;
-  readonly label: string;
-  readonly icon: ComponentType<{ className?: string | undefined }>;
-  /** Sort weight (lower first). Default 100. */
-  readonly order?: number;
-  readonly appliesTo?: (ctx: SessionContext) => boolean;
-  readonly render: (ctx: SecondaryDrawerTabContext) => ReactNode;
-}
-
-// ── Activity renderers ─────────────────────────────────────────────────
-
-export interface ActivityRendererContext {
-  readonly session: SessionContext;
-  readonly event: SessionActivityEvent;
-}
-
-export interface ActivityRendererContribution {
-  /** Namespaced id (`<biome-id>/<renderer>`). */
-  readonly id: string;
-  /**
-   * Activity entry kind this renderer handles. Either an exact
-   * `SessionConsoleEntry.kind` value or a namespaced custom kind a
-   * biome emits through its own backend events.
-   */
-  readonly entryKind: string;
-  /** Per-event predicate; defaults to "always handle this kind". */
-  readonly appliesTo?: (ctx: ActivityRendererContext) => boolean;
-  readonly render: (ctx: ActivityRendererContext) => ReactNode;
-}
-
-// ── Tool-call renderers ────────────────────────────────────────────────
-
-export interface ToolCallRendererContext {
-  readonly session: SessionContext;
-  readonly event: SessionToolCallEvent;
-}
-
-export interface ToolCallRendererContribution {
-  /** Namespaced id (`<biome-id>/<renderer>`). */
-  readonly id: string;
-  /**
-   * Either an exact tool name (`'bash_run'`) OR a `'<prefix>.*'` glob
-   * matching any tool whose name starts with `<prefix>.` (e.g.
-   * `'jira.*'`). Exact matches win over globs; ties broken by `weight`.
-   */
-  readonly toolName: string;
-  readonly icon?: ComponentType<{ className?: string | undefined }>;
-  readonly weight?: number;
-  readonly appliesTo?: (ctx: ToolCallRendererContext) => boolean;
-  /** Short label shown in the activity timeline row. */
-  readonly renderLabel?: (ctx: ToolCallRendererContext) => string;
-  /**
-   * Expanded card / inline body for the tool call. When omitted, the
-   * host falls back to a generic key-value dump of args + result.
-   */
-  readonly render?: (ctx: ToolCallRendererContext) => ReactNode;
-}
-
-// ── Mutation bars ──────────────────────────────────────────────────────
-
-export interface MutationBarContext {
-  readonly session: SessionContext;
-  readonly bridge: HostBridge;
-}
-
-/**
- * Sticky bar rendered between the session header and the chat panel —
- * used today by software-dev for the git branch + PR status row. Generic
- * by design so a Jira biome could add an "Issue: PROJ-123 / In Review"
- * bar, an aws biome could surface a deploy status, etc.
- */
-export interface MutationBarContribution {
-  /** Namespaced id (`<biome-id>/<bar>`). */
-  readonly id: string;
-  /** Sort weight (lower renders higher). Default 100. */
-  readonly order?: number;
-  readonly appliesTo?: (ctx: SessionContext) => boolean;
-  readonly render: (ctx: MutationBarContext) => ReactNode;
-}
-
-// ── Header chips ───────────────────────────────────────────────────────
-
-export interface HeaderChipContext {
-  readonly session: SessionContext;
-  readonly bridge: HostBridge;
-}
-
-/**
- * Compact chips rendered in the session header row alongside the title
- * (e.g. "Fork of #42", "PR #15", "Catalog entity: …"). Biomes use
- * these for one-glance links to external systems.
- */
-export interface HeaderChipContribution {
-  readonly id: string;
-  readonly order?: number;
-  readonly appliesTo?: (ctx: SessionContext) => boolean;
-  readonly render: (ctx: HeaderChipContext) => ReactNode;
-}
-
-// ── Attachment classes ─────────────────────────────────────────────────
-
-export interface AttachmentPickResult {
-  /** Class id (`<biome-id>/<class>`). */
-  readonly classId: string;
-  /** Stable reference the backend uses to resolve the attachment. */
-  readonly ref: string;
-  /** Display label shown in the attachments list. */
-  readonly label: string;
-  /** Optional opaque payload forwarded to the attachment API. */
-  readonly payload?: Record<string, unknown>;
-}
-
-export interface AttachmentPickContext {
-  readonly session: SessionContext;
-  readonly bridge: HostBridge;
-}
-
-/**
- * A class of attachable resource a biome contributes. The contribution
- * supplies a label, an icon, and a picker callback that resolves to a
- * concrete attachment ref. The host calls `pickAndAttach` from its
- * attachment dialog when the user selects this class.
- */
-export interface AttachmentClassContribution {
-  readonly id: string;
-  readonly label: string;
-  readonly description?: string;
-  readonly icon?: ComponentType<{ className?: string | undefined }>;
-  readonly order?: number;
-  readonly appliesTo?: (ctx: SessionContext) => boolean;
-  readonly pickAndAttach: (
-    ctx: AttachmentPickContext,
-  ) => Promise<AttachmentPickResult | null>;
-}
-
-// ── Aggregate session contributions ────────────────────────────────────
-
-/**
- * All session-level contributions a biome declares on its
- * `FrontendBiome`. Every field is optional; a biome opts in only to
- * the surfaces it cares about. The host walks the registry once per
- * surface and assembles the active contributions for the current
- * session context.
- */
-export interface SessionContributions {
-  readonly slashCommands?: readonly SlashCommandContribution[];
-  readonly secondaryDrawerTabs?: readonly SecondaryDrawerTabContribution[];
-  readonly activityRenderers?: readonly ActivityRendererContribution[];
-  readonly toolCallRenderers?: readonly ToolCallRendererContribution[];
-  readonly mutationBars?: readonly MutationBarContribution[];
-  readonly headerChips?: readonly HeaderChipContribution[];
-  readonly attachmentClasses?: readonly AttachmentClassContribution[];
-}

package/src/lib/biome-host/use-mutation-with-error-toast.ts

@@ -1,90 +0,0 @@
-/**
- * Unified mutation hook with automatic success/error toast notifications.
- *
- * Rebuilt on the {@link HostBridge}: toasts route through `bridge.toast` and
- * error copy is decoded by the bridge's error decoder (falling back to the
- * kernel {@link getUserFacingErrorMessage}). Biome code stays decoupled from
- * any particular toast library or error-envelope shape.
- *
- * Requires `@tanstack/react-query` (an optional peer of the kernel) and a
- * `QueryClientProvider` mounted above.
- *
- * Usage:
- *   const mutation = useMutationWithErrorToast(
- *     { mutationFn: (vars) => apiFn(vars), onSuccess: () => invalidate() },
- *     { successTitle: 'Saved', errorTitle: 'Save failed' },
- *   );
- */
-import { useMutation, type UseMutationOptions } from '@tanstack/react-query';
-
-import { getUserFacingErrorMessage } from './errors';
-import { useHostBridge } from './host-bridge';
-
-export type MutationCoreOptions<
-  TData = unknown,
-  TError = Error,
-  TVariables = unknown,
-  TContext = unknown,
-> = Omit<UseMutationOptions<TData, TError, TVariables, TContext>, 'onError'>;
-
-export interface MutationToastOptions<TError = Error> {
-  /** Title for the success toast. Omit or pass null to suppress the success toast. */
-  successTitle?: string | null;
-  /** Optional description for the success toast. */
-  successDescription?: string;
-  /** Title for the error toast. Omit to suppress the error toast. */
-  errorTitle?: string;
-  /**
-   * Custom error side-effect. Called before the auto-error-toast.
-   * Return `true` to suppress the automatic toast.
-   */
-  onError?: (error: TError) => boolean | void;
-}
-
-export function useMutationWithErrorToast<
-  TData = unknown,
-  TError extends Error = Error,
-  TVariables = unknown,
-  TContext = unknown,
->(
-  mutationOptions: MutationCoreOptions<TData, TError, TVariables, TContext>,
-  toastOptions?: MutationToastOptions<TError>,
-) {
-  const bridge = useHostBridge();
-  const decodeError =
-    bridge.errors?.getUserFacingErrorMessage ?? getUserFacingErrorMessage;
-
-  const { onSuccess: userOnSuccess, ...coreMutationOptions } = mutationOptions;
-  const {
-    successTitle,
-    successDescription,
-    errorTitle,
-    onError: customOnError,
-  } = toastOptions ?? {};
-
-  return useMutation({
-    ...coreMutationOptions,
-    onSuccess: (data, variables, context, mutation) => {
-      if (successTitle !== null && successTitle !== undefined) {
-        bridge.toast.success(successTitle, successDescription);
-      }
-      if (userOnSuccess) {
-        userOnSuccess(data, variables, context, mutation);
-      }
-    },
-    onError: (error: TError) => {
-      if (errorTitle !== undefined) {
-        const shouldSuppressToast = customOnError?.(error) === true;
-        if (!shouldSuppressToast) {
-          const errorMessage = decodeError(
-            error,
-            'Unable to complete this action.',
-          );
-          bridge.toast.error(errorTitle, errorMessage);
-        }
-      } else {
-        customOnError?.(error);
-      }
-    },
-  });
-}