@xemahq/kernel-contracts 0.49.3 → 0.56.0

package/src/subject/lib/subject.ts

@@ -45,11 +45,27 @@ export const SubjectKindSchema = z.nativeEnum(SubjectKind);
 export interface ActingForRef {
   kind: SubjectKind;
   id: string;
+  /**
+   * The ISSUER-STAMPED OAuth client identity of this hop (`azp`, else
+   * `client_id`), when the issuer stamps it inside the hop's `act` object.
+   *
+   * `id` is the hop's `sub` — for a service-account token that is an opaque
+   * Keycloak UUID, which says nothing about WHICH service conveyed the call.
+   * The client id is the logical service name (`workflow-runtime-worker`,
+   * `agent-session-api`, …) that grants and audit trails are keyed by. It is
+   * never caller-supplied: an OAuth client cannot assert another client's id
+   * in a token the issuer signed.
+   *
+   * Absent when the issuer stamps neither claim on the hop — treat absence as
+   * "unknown", never as a match.
+   */
+  clientId?: string;
 }
 
 export const ActingForRefSchema = z.object({
   kind: SubjectKindSchema,
   id: z.string().min(1),
+  clientId: z.string().min(1).optional(),
 }) as z.ZodType<ActingForRef>;
 
 /**

package/src/surface/index.ts

@@ -0,0 +1,3 @@
+export * from './lib/surface-kind';
+export * from './lib/vista-surface';
+export * from './lib/surface-contribution';

package/src/surface/lib/surface-contribution.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+
+/**
+ * Manifest shape carried by every `ContributionKind.SurfaceKind` envelope.
+ *
+ * One contribution = one Vista surface kind. The shape is STRUCTURALLY
+ * IDENTICAL to `WidgetContributionManifest` (see
+ * `../../widget/lib/widget-contribution.ts`) — the two planes deliberately
+ * share one contribution pattern, so the generic
+ * `BootstrapContributionsService<TKind, TManifest>` template and the biome-host
+ * `KindParser` ingest a surface kind exactly the way a widget kind is ingested.
+ * Provenance (`biomeId`, `biomeVersion`) is stamped by the ingestion pipeline
+ * from the discovering biome's manifest — authors do NOT declare it inline.
+ *
+ * A biome contributes a surface kind so its frontend biome can register a
+ * renderer for it against the `<biomeId>:<kind>` slug. The `kind` here is the
+ * BARE, biome-local kind slug; the catalogue namespaces it at ingest so it can
+ * never shadow a first-party {@link SurfaceKind}.
+ *
+ * Validation is fail-fast: a contribution that violates any constraint is
+ * rejected at boot. `payloadSchema` is an opaque JSON Schema passed through
+ * verbatim (the catalogue surfaces it to the frontend — which derives the
+ * GENERIC schema-driven renderer from it — and to authoring tools; it is NOT a
+ * kernel-validated shape, because validating it as JSON Schema here would be
+ * either partial or pull in a JSON-Schema validator, violating the kernel-leaf
+ * invariant).
+ *
+ * Per the 2-file rule for a new `ContributionKind`, the kernel owns exactly
+ * this manifest schema plus the enum member; the per-kind ingestion PARSER
+ * lives in the consuming service (`biome-host-api`), not here.
+ */
+export interface SurfaceContributionManifest {
+  /**
+   * Biome-local kind slug (lowercase, hyphenated). Namespaced to
+   * `<biomeId>:<kind>` by the catalogue — a biome can never claim a bare
+   * first-party kind.
+   */
+  readonly kind: string;
+  /** Monotonic schema version for this kind's payload. */
+  readonly version: number;
+  /** Human-readable display name surfaced in the catalogue (≤ 200 chars). */
+  readonly displayName: string;
+  /** One-line summary of WHAT the surface shows + WHEN to open it (≤ 1000 chars). */
+  readonly summary: string;
+  /** JSON Schema for the surface payload — passed through verbatim. */
+  readonly payloadSchema: Record<string, unknown>;
+}
+
+const SURFACE_KIND_SLUG_REGEX = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Zod validator for {@link SurfaceContributionManifest}. The biome-host parser
+ * and the catalogue's register route BOTH route every candidate manifest
+ * through this before persisting, so a malformed contribution fails at the
+ * boundary instead of at render time.
+ */
+export const SurfaceContributionManifestSchema: z.ZodType<SurfaceContributionManifest> =
+  z.object({
+    kind: z
+      .string()
+      .min(1)
+      .max(100)
+      .regex(
+        SURFACE_KIND_SLUG_REGEX,
+        'Surface kind slug must be lowercase letters, digits, and hyphens (start with a letter).',
+      ),
+    version: z.number().int().positive(),
+    displayName: z.string().min(1).max(200),
+    summary: z.string().min(1).max(1000),
+    payloadSchema: z.record(z.string(), z.unknown()),
+  }) as z.ZodType<SurfaceContributionManifest>;
+
+/** Provenance of a surface-kind catalogue entry. Closed set. */
+export enum SurfaceKindSource {
+  FirstParty = 'first-party',
+  Biome = 'biome',
+}
+
+export const SurfaceKindSourceSchema = z.nativeEnum(SurfaceKindSource);
+
+/**
+ * A resolved surface-kind catalogue entry — what the surface-kind catalogue
+ * endpoint returns. It unifies the closed first-party set and the open
+ * biome-contributed set behind ONE shape the frontend consumes to know which
+ * kinds exist (and to register biome-contributed kinds into the open Vista
+ * registry with a generic schema-driven renderer).
+ *
+ * `source` discriminates provenance; `kind` is the FULLY-NAMESPACED slug the
+ * frontend registry keys by (a first-party kind is its bare enum value; a biome
+ * kind is `<biomeId>:<kind>`).
+ */
+export interface SurfaceKindCatalogueEntry {
+  readonly kind: string;
+  readonly version: number;
+  readonly displayName: string;
+  readonly summary: string;
+  readonly payloadSchema: Record<string, unknown>;
+  readonly source: SurfaceKindSource;
+  /** Present only for biome-contributed kinds. */
+  readonly biomeId?: string;
+}

package/src/surface/lib/surface-kind.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+
+/**
+ * `SurfaceKind` — the closed first-party set of render kinds a Vista tab can
+ * hold (Canopy Plane ④, "Vista: the render plane").
+ *
+ * Vista is the agent-driven, biome-extensible tabbed preview plane: the agent
+ * opens a tab by emitting a {@link VistaSurface} envelope, and the frontend
+ * resolves the envelope's `kind` to a renderer. Each first-party kind is a
+ * GENERIC, domain-agnostic presentation primitive — chosen to cover the
+ * broadest possible range of "thing the agent wants to show the user" without
+ * baking in any vertical semantics.
+ *
+ * ── Closed first-party set vs. open biome set ───────────────────────────────
+ * A biome contributes its OWN surface kind as a namespaced string
+ * (`<biomeId>:<kind>`) through a `ContributionKind.SurfaceKind` contribution —
+ * it never extends this enum. This is the same closed-enum + open-namespaced-
+ * string pattern as `ChatWidgetKind` (see `../../widget`): the frontend
+ * registry reserves every value below, so a biome can never shadow a
+ * first-party kind.
+ *
+ * Adding a first-party kind = one enum member here + a renderer registered
+ * into the frontend Vista registry's closed set.
+ */
+export enum SurfaceKind {
+  /** An external URL rendered in the preview chrome (address bar + frame). */
+  Url = 'url',
+  /** A first-party in-app web view (a host route rendered inside the tab). */
+  Web = 'web',
+  /** UNTRUSTED HTML rendered in an opaque-origin, script-sandboxed frame. */
+  Html = 'html',
+  /** A Markdown document. */
+  Markdown = 'markdown',
+  /** A source file with syntax highlighting. */
+  Code = 'code',
+  /** A unified diff (one or more files). */
+  Diff = 'diff',
+  /** A JSON document rendered as an inspectable tree. */
+  Json = 'json',
+  /** Generic columns + rows. The universal "show me structured records". */
+  Table = 'table',
+  /** A chart over labelled series. */
+  Chart = 'chart',
+  /** A PDF document (canvas-rendered, no script execution). */
+  Pdf = 'pdf',
+  /** A still image. */
+  Image = 'image',
+  /** Time-based media (audio/video). */
+  Media = 'media',
+  /** A Xema object rendered through its registered object view. */
+  Object = 'object',
+  /** A biome's REAL React route, reached through an `xema://biome/…` deeplink. */
+  BiomeRoute = 'biome-route',
+  /** A schema-driven form — the secure-elicitation surface. */
+  Form = 'form',
+  /** A runtime app (App Platform) rendered in its own frame. */
+  App = 'app',
+  /** A file tree / browser over a workspace or artifact set. */
+  Files = 'files',
+  /** A node-edge graph (e.g. the capability map). */
+  Graph = 'graph',
+}
+
+/** Zod mirror of {@link SurfaceKind} for wire-boundary validation. */
+export const SurfaceKindSchema = z.nativeEnum(SurfaceKind);

package/src/surface/lib/vista-surface.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+
+/**
+ * `VistaSurface` — one Vista tab. The agent opens/updates a tab by emitting
+ * this envelope; the frontend Vista registry resolves `kind` to a renderer and
+ * hands it the validated `payload`.
+ *
+ * `kind` is a first-party {@link SurfaceKind} value OR a namespaced biome
+ * string (`<biomeId>:<kind>`). `version` is the monotonic schema version for
+ * THIS kind — the frontend renders the registered renderer when `version <=
+ * supportedVersion`, else a safe fallback card. `payload` is the kind-specific
+ * payload (validated by the producer against the kind's JSON Schema; the
+ * frontend re-validates before render so a malformed payload renders the
+ * fallback rather than being dropped).
+ *
+ * Structurally this is `ChatWidgetEnvelope` plus the tab identity a preview
+ * plane needs (`tabId`, `title`, `pinned`) — deliberately so: the two planes
+ * share ONE contribution pattern, one registry core, and one three-layer
+ * renderer fallback.
+ */
+export interface VistaSurface {
+  /** Stable identity of the tab. Re-opening the same `tabId` replaces it. */
+  readonly tabId: string;
+  /** First-party {@link SurfaceKind} value, or a `<biomeId>:<kind>` slug. */
+  readonly kind: string;
+  /** Monotonic schema version for this kind's payload. */
+  readonly version: number;
+  /** Tab label. */
+  readonly title: string;
+  /** Kind-specific payload, validated + narrowed by the frontend registry. */
+  readonly payload: unknown;
+  /** A pinned tab survives the agent closing/replacing unpinned tabs. */
+  readonly pinned?: boolean;
+}
+
+/** Zod validator for {@link VistaSurface}. */
+export const VistaSurfaceSchema: z.ZodType<VistaSurface> = z.object({
+  tabId: z.string().min(1),
+  kind: z.string().min(1),
+  version: z.number().int().positive(),
+  title: z.string().min(1),
+  payload: z.unknown(),
+  pinned: z.boolean().optional(),
+}) as z.ZodType<VistaSurface>;

package/src/widget/lib/chat-widget-envelope.ts

@@ -31,8 +31,12 @@ export const ChatWidgetEnvelopeSchema: z.ZodType<ChatWidgetEnvelope> = z.object(
 
 /**
  * Why a widget fell back to the safe card — populated on the FE resolved
- * decision so the Studio debugger can see WHY. Mirror of the FE
- * `ChatWidgetFallbackReason`. Closed set.
+ * decision so the Studio debugger can see WHY. Closed set.
+ *
+ * This is the WIRE mirror. The FE runtime reason set is
+ * `ContributionFallbackReason` in `@xemahq/ui-kernel`, shared by every plane
+ * built on the two-layer contribution registry (ChatWidgets, Vista surfaces) —
+ * keep the two value-identical.
  */
 export enum ChatWidgetFallbackReason {
   UnknownKind = 'unknown-kind',

package/src/workflow/lib/enums.ts

@@ -288,13 +288,12 @@ export enum BuiltInActionId {
    * authorization decisions, so any cross-service side-effect routes
    * through this action and the router's grant resolver decides.
    *
-   * Inputs declare the `ref` (`<domain>:<resource>.<verb>@<major>`),
-   * the opaque `input` payload the bound implementation consumes, and
-   * an optional `subjectOverride` for callers that need to act as a
-   * different subject than the workflow's executing identity. The
-   * activity derives `subject` from the worker's service identity
-   * when no override is supplied and stamps `correlationId` with the
-   * workflow run id so audit-log entries stitch back to the run.
+   * Inputs declare the `ref` (`<domain>:<resource>.<verb>@<major>`) and
+   * the opaque `input` payload the bound implementation consumes. The
+   * subject is not an input: the activity always derives it from the
+   * worker's own service identity — the identity whose bearer the
+   * router verifies — and stamps `correlationId` with the workflow run
+   * id so audit-log entries stitch back to the run.
    */
   CAPABILITY_INVOKE = 'xema/capability',
   /**

package/dist/capability/lib/first-party-capability-domains.d.ts

@@ -1,30 +0,0 @@
-import { z } from 'zod';
-export declare const FIRST_PARTY_CAPABILITY_DOMAINS: readonly ["xema-shell", "store", "biome", "connector", "kb", "agent", "memory", "model", "model-resolution", "mcp-tool", "workflow", "studio", "interactive-session", "agent-session", "document", "notification", "space", "mailops", "workspace", "worker-runtime", "artifact", "search", "app"];
-export type FirstPartyCapabilityDomain = (typeof FIRST_PARTY_CAPABILITY_DOMAINS)[number];
-export declare const FirstPartyCapabilityDomainSchema: z.ZodEnum<{
-    search: "search";
-    kb: "kb";
-    memory: "memory";
-    agent: "agent";
-    studio: "studio";
-    "agent-session": "agent-session";
-    document: "document";
-    artifact: "artifact";
-    app: "app";
-    workflow: "workflow";
-    connector: "connector";
-    biome: "biome";
-    model: "model";
-    "xema-shell": "xema-shell";
-    store: "store";
-    "model-resolution": "model-resolution";
-    "mcp-tool": "mcp-tool";
-    "interactive-session": "interactive-session";
-    notification: "notification";
-    space: "space";
-    mailops: "mailops";
-    workspace: "workspace";
-    "worker-runtime": "worker-runtime";
-}>;
-export declare function isFirstPartyCapabilityDomain(domain: string): domain is FirstPartyCapabilityDomain;
-//# sourceMappingURL=first-party-capability-domains.d.ts.map

package/dist/capability/lib/first-party-capability-domains.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"first-party-capability-domains.d.ts","sourceRoot":"","sources":["../../../src/capability/lib/first-party-capability-domains.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0BxB,eAAO,MAAM,8BAA8B,oSAwBjC,CAAC;AAEX,MAAM,MAAM,0BAA0B,GACpC,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC;AAElD,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;EAK5C,CAAC;AAYF,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,GACb,MAAM,IAAI,0BAA0B,CAEtC"}

package/dist/capability/lib/first-party-capability-domains.js

@@ -1,36 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.FirstPartyCapabilityDomainSchema = exports.FIRST_PARTY_CAPABILITY_DOMAINS = void 0;
-exports.isFirstPartyCapabilityDomain = isFirstPartyCapabilityDomain;
-const zod_1 = require("zod");
-exports.FIRST_PARTY_CAPABILITY_DOMAINS = [
-    'xema-shell',
-    'store',
-    'biome',
-    'connector',
-    'kb',
-    'agent',
-    'memory',
-    'model',
-    'model-resolution',
-    'mcp-tool',
-    'workflow',
-    'studio',
-    'interactive-session',
-    'agent-session',
-    'document',
-    'notification',
-    'space',
-    'mailops',
-    'workspace',
-    'worker-runtime',
-    'artifact',
-    'search',
-    'app',
-];
-exports.FirstPartyCapabilityDomainSchema = zod_1.z.enum(exports.FIRST_PARTY_CAPABILITY_DOMAINS);
-const FIRST_PARTY_CAPABILITY_DOMAIN_SET = new Set(exports.FIRST_PARTY_CAPABILITY_DOMAINS);
-function isFirstPartyCapabilityDomain(domain) {
-    return FIRST_PARTY_CAPABILITY_DOMAIN_SET.has(domain);
-}
-//# sourceMappingURL=first-party-capability-domains.js.map

package/dist/capability/lib/first-party-capability-domains.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"first-party-capability-domains.js","sourceRoot":"","sources":["../../../src/capability/lib/first-party-capability-domains.ts"],"names":[],"mappings":";;;AAwEA,oEAIC;AA5ED,6BAAwB;AA0BX,QAAA,8BAA8B,GAAG;IAC5C,YAAY;IACZ,OAAO;IACP,OAAO;IACP,WAAW;IACX,IAAI;IACJ,OAAO;IACP,QAAQ;IACR,OAAO;IACP,kBAAkB;IAClB,UAAU;IACV,UAAU;IACV,QAAQ;IACR,qBAAqB;IACrB,eAAe;IACf,UAAU;IACV,cAAc;IACd,OAAO;IACP,SAAS;IACT,WAAW;IACX,gBAAgB;IAChB,UAAU;IACV,QAAQ;IACR,KAAK;CACG,CAAC;AAKE,QAAA,gCAAgC,GAAG,OAAC,CAAC,IAAI,CACpD,sCAGC,CACF,CAAC;AAEF,MAAM,iCAAiC,GAAwB,IAAI,GAAG,CACpE,sCAA8B,CAC/B,CAAC;AAQF,SAAgB,4BAA4B,CAC1C,MAAc;IAEd,OAAO,iCAAiC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACvD,CAAC"}

package/src/capability/lib/first-party-capability-domains.ts

@@ -1,77 +0,0 @@
-import { z } from 'zod';
-
-// ═══════════════════════════════════════════════════════════════════════════
-// ── The CLOSED set of first-party capability DOMAINS ──
-//
-// A capability ref is `<domain>:<resource>.<verb>@<major>`. A DOMAIN is
-// "first-party" when a fixed in-the-box Xema platform service owns every ref
-// under it — i.e. the capability-router's static dispatch table resolves it
-// directly (never through an org-provisioned or contributed backing).
-//
-// This is the SINGLE SOURCE OF TRUTH for that membership. It exists so two
-// services can agree without one reaching into the other's code:
-//
-//   - `xema-capability-router` builds its static dispatch table from EXACTLY
-//     these keys and asserts the two agree at boot (fail-fast on drift).
-//   - `capability-registry-api` REFUSES an org `CapabilityProviderBinding`
-//     whose ref domain is in this set — an org admin must not be able to bind
-//     `kb:page.read@1` / `agent:invoke@1` / `artifact:blob.read@1` to a URL
-//     they control and silently shadow the platform data plane.
-//
-// Membership is the router's dispatch keys, in dispatch-registration order.
-// Adding/removing a first-party domain is a coordinated change here PLUS the
-// router's dispatch table — the boot assertion turns any divergence into a
-// crash rather than a silent shadow window.
-// ═══════════════════════════════════════════════════════════════════════════
-
-export const FIRST_PARTY_CAPABILITY_DOMAINS = [
-  'xema-shell',
-  'store',
-  'biome',
-  'connector',
-  'kb',
-  'agent',
-  'memory',
-  'model',
-  'model-resolution',
-  'mcp-tool',
-  'workflow',
-  'studio',
-  'interactive-session',
-  'agent-session',
-  'document',
-  'notification',
-  'space',
-  'mailops',
-  'workspace',
-  'worker-runtime',
-  'artifact',
-  'search',
-  'app',
-] as const;
-
-export type FirstPartyCapabilityDomain =
-  (typeof FIRST_PARTY_CAPABILITY_DOMAINS)[number];
-
-export const FirstPartyCapabilityDomainSchema = z.enum(
-  FIRST_PARTY_CAPABILITY_DOMAINS as unknown as [
-    FirstPartyCapabilityDomain,
-    ...FirstPartyCapabilityDomain[],
-  ],
-);
-
-const FIRST_PARTY_CAPABILITY_DOMAIN_SET: ReadonlySet<string> = new Set(
-  FIRST_PARTY_CAPABILITY_DOMAINS,
-);
-
-/**
- * `true` iff `domain` is a first-party platform capability domain. O(1)
- * membership over the closed set above. The write-path shadow refusal and the
- * router's binding-skip defense-in-depth both branch on this — never on an
- * ad-hoc string compare or a hand-maintained second list.
- */
-export function isFirstPartyCapabilityDomain(
-  domain: string,
-): domain is FirstPartyCapabilityDomain {
-  return FIRST_PARTY_CAPABILITY_DOMAIN_SET.has(domain);
-}