@xemahq/ui-kernel 0.1.4

package/src/lib/biome-host/nav.ts

@@ -0,0 +1,83 @@
+import type { ComponentType } from 'react';
+
+import { biomeRegistry } from './biome-registry';
+
+export interface NavItem {
+  readonly key: string;
+  readonly label: string;
+  readonly icon?: ComponentType<{ className?: string | undefined }> | undefined;
+  readonly weight?: number | undefined;
+  /** True when this item came from a biome contribution. */
+  readonly fromBiome?: boolean | undefined;
+}
+
+export interface NavSection {
+  readonly heading?: string | undefined;
+  readonly items: readonly NavItem[];
+}
+
+/**
+ * Merge the host's core nav sections with biome nav contributions. Biome
+ * items are bucketed into the section whose `heading` matches their
+ * `section` field; if no match exists, a synthetic section is appended.
+ *
+ * Sort is deterministic: by `(weight, key)` — every host renders the same
+ * order from the same registry state, so tests stay reproducible.
+ */
+export function mergeNavSections(coreSections: readonly NavSection[]): readonly NavSection[] {
+  const sectionMap = new Map<string, NavItem[]>();
+  const sectionOrder: string[] = [];
+
+  for (const section of coreSections) {
+    const heading = section.heading ?? '';
+    sectionOrder.push(heading);
+    sectionMap.set(heading, [...section.items]);
+  }
+
+  for (const biome of biomeRegistry.list()) {
+    for (const navItem of biome.navItems ?? []) {
+      const heading = navItem.section ?? '';
+      let bucket = sectionMap.get(heading);
+      if (!bucket) {
+        bucket = [];
+        sectionOrder.push(heading);
+        sectionMap.set(heading, bucket);
+      }
+      bucket.push({
+        key: navItem.id,
+        label: navItem.label,
+        icon: navItem.icon,
+        weight: navItem.weight,
+        fromBiome: true,
+      });
+    }
+  }
+
+  return sectionOrder.map((heading) => ({
+    heading: heading === '' ? undefined : heading,
+    items: (sectionMap.get(heading) ?? []).slice().sort((a, b) => {
+      const wa = a.weight ?? 100;
+      const wb = b.weight ?? 100;
+      if (wa !== wb) return wa - wb;
+      return a.key.localeCompare(b.key);
+    }),
+  }));
+}
+
+/**
+ * Build a `{ navKey: routePath }` map merging core feature-key→route entries
+ * with biome nav-item route paths. Biome-contributed entries win over
+ * core entries with the same key (intentional — biome authors who pick a
+ * conflicting id are signalling override intent).
+ */
+export function mergeFeatureRouteMap(
+  coreFeatureRoutes: Readonly<Record<string, string>>,
+): Record<string, string> {
+  const out: Record<string, string> = { ...coreFeatureRoutes };
+  for (const biome of biomeRegistry.list()) {
+    for (const navItem of biome.navItems ?? []) {
+      out[navItem.id] = navItem.route;
+    }
+  }
+  return out;
+}

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

@@ -0,0 +1,293 @@
+/**
+ * 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 a profile, capability flag, session status, or any
+ * derived condition. 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 { ComponentType, ReactNode } from 'react';
+
+import type { HostBridge } from './host-bridge';
+import type { SessionProfileDescriptor } from './session-profiles';
+
+/**
+ * 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 profileKey?: string;
+  readonly status: string;
+  /**
+   * Capability flags advertised by the session's profile descriptor
+   * (e.g. `'hasGit'`, `'hasArtifacts'`, `'supportsBranches'`). Biomes
+   * gate against these instead of hard-coding profile keys.
+   */
+  readonly capabilities: ReadonlySet<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;
+}
+
+/**
+ * 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[];
+  /**
+   * Profile descriptors this biome owns. The host matches a session's
+   * `profileKey` against these and fans out the descriptor's
+   * `capabilities` as `SessionContext.capabilities`, which each
+   * contribution's `appliesTo` predicate reads. A biome that ships a
+   * profile MUST also ship its descriptor here so the capability vocab
+   * stays explicit rather than implicit-from-key-naming.
+   */
+  readonly profiles?: readonly SessionProfileDescriptor[];
+}

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

@@ -0,0 +1,99 @@
+/**
+ * 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]);
+}

package/src/lib/system-bus/capability-invoke.ts

@@ -0,0 +1,92 @@
+import type { CapabilityRef } from '@xemahq/kernel-contracts/capability';
+import type { SpaceRef } from '@xemahq/kernel-contracts/space';
+
+/**
+ * Orchestration metadata the SystemBus carries on every
+ * `capability.invoke` so the backend capability-router can build its
+ * `ExecutionContext` envelope and record who invoked what, from where,
+ * in which space, against which environment.
+ *
+ * **This is pure orchestration data. The SystemBus NEVER inspects it to
+ * decide allow/deny.** The backend capability-router is the single
+ * authority on auth / tenancy / policy / audit. The SystemBus's only job
+ * is to faithfully relay this metadata to the router and pass the result
+ * back; it adds no authorization of its own.
+ *
+ * The fields map 1:1 onto the gateway's per-invocation envelope:
+ * - `sourceBiomeId`    → `ExecutionContext.biome.id`
+ * - `targetCapabilityRef` → `ExecutionContext.capability.ref`
+ * - `spaceRef`         → `ExecutionContext.space`
+ * - `environmentId`    → `ExecutionContext.environment.id`
+ * - `actorId`          → `ExecutionContext.subject` (the host resolves the
+ *                        full SubjectRef from the actor's session).
+ */
+export interface CapabilityInvokeMeta {
+  /** Biome that originated the invocation (for provenance + audit). */
+  readonly sourceBiomeId: string;
+  /** The capability being invoked. Mirrors the `ref` argument; carried
+   * explicitly so the metadata is self-describing in audit records. */
+  readonly targetCapabilityRef: CapabilityRef;
+  /** The space (5/7-tier scope) the invocation runs in. */
+  readonly spaceRef: SpaceRef;
+  /** Canonical `environment:<slug>` ref of the active execution environment. */
+  readonly environmentId: string;
+  /** The acting subject's id (user / agent / app). The host expands this
+   * into the full `SubjectRef` server-side; the SystemBus only carries
+   * the id, never a credential. */
+  readonly actorId: string;
+}
+
+/**
+ * Result of a `capability.invoke`. Mirrors the capability-router's
+ * `InvokeMetaToolResponseDto` wire shape (`output? / auditId /
+ * obligations`) without importing the generated client — the kernel
+ * contract stays framework- and transport-agnostic.
+ *
+ * `output` is `undefined` on denial / approval-required outcomes; the
+ * caller MUST treat its absence explicitly (fetch the structured denial
+ * via `auditId`) rather than assume success. `auditId` is ALWAYS
+ * populated, including on denial — this is the audit anchor.
+ */
+export interface CapabilityInvokeResult<TOutput = unknown> {
+  /** Capability output payload. Omitted on denial / approval-required. */
+  readonly output?: TOutput;
+  /** Audit entry id. Always populated, including on denial. */
+  readonly auditId: string;
+  /**
+   * Closed-set policy obligations the caller must honour locally
+   * (e.g. `redact-secrets`, `max-cost-usd`). Sourced verbatim from the
+   * router response. The string union is left open at the contract layer
+   * because the obligation enum is owned by `@xemahq/kernel-contracts/policy`;
+   * the host maps these to the typed enum when it honours them.
+   */
+  readonly obligations: readonly string[];
+}
+
+/**
+ * The `capability.invoke` surface of the SystemBus.
+ *
+ * `invoke()` routes the call to the host's capability-router client. The
+ * backend enforces auth / tenancy / policy / audit; the SystemBus adds
+ * NONE of those — it is pure orchestration. A non-2xx transport failure
+ * rejects the returned promise (fail-fast); a *policy denial* resolves
+ * with `output === undefined` + a populated `auditId` (the router's
+ * structured outcome), so denial is observable, never silently swallowed.
+ */
+export interface CapabilityBus {
+  /**
+   * Invoke a capability through the backend router.
+   *
+   * @param ref   The capability to invoke (`<domain>:<resource>.<verb>@<major>`).
+   * @param input The capability input payload (validated server-side
+   *              against the descriptor's `inputSchema`).
+   * @param meta  Orchestration metadata for the `ExecutionContext`.
+   *              The host fills `targetCapabilityRef` from `ref` if the
+   *              caller omits it; all other fields are required.
+   */
+  invoke<TInput = unknown, TOutput = unknown>(
+    ref: CapabilityRef,
+    input: TInput,
+    meta: CapabilityInvokeMeta,
+  ): Promise<CapabilityInvokeResult<TOutput>>;
+}