@xemahq/kernel-contracts 0.1.0

package/src/capability/lib/meta-tool.ts

@@ -0,0 +1,213 @@
+import { z } from 'zod';
+
+import { CapabilityRefSchema, type CapabilityRef } from './capability-ref';
+
+/**
+ * Xema OS Phase H — the agent-facing MCP surface collapses to exactly three
+ * meta-tools. The set is CLOSED — no free-form strings — so we ship the
+ * canonical names as a kernel enum that the router controller, the
+ * mcp-gateway federation bridge, and any downstream client can all agree on.
+ *
+ * Plan-of-record:
+ *   `.claude/plans/following-up-the-xema-os-plan-md-abstract-stream.md` §6.H
+ *
+ * The string values are the wire names emitted to OpenCode via the
+ * mcp-gateway federation bridge (`resolveAsMetaTools()`). They are also the
+ * suffix segments of the router HTTP routes:
+ *
+ *   POST /xema/capabilities/list      → MetaToolName.List
+ *   POST /xema/capabilities/describe  → MetaToolName.Describe
+ *   POST /xema/capabilities/invoke    → MetaToolName.Invoke
+ */
+export enum MetaToolName {
+  List = 'xema.capabilities.list',
+  Describe = 'xema.capabilities.describe',
+  Invoke = 'xema.capabilities.invoke',
+}
+
+export const MetaToolNameSchema = z.nativeEnum(MetaToolName);
+
+/**
+ * Wire-side audit topic for every meta-tool invocation (Phase H.5). Kept here
+ * — not in a service — so analytics consumers and the router emit the same
+ * string.
+ */
+export const META_TOOL_AUDIT_TOPIC = 'capability.invoked.v1';
+
+/**
+ * The route suffix for each meta-tool, mounted under `/xema/capabilities` on
+ * the capability-router. The router controller MUST consume this map instead
+ * of inlining the path strings, so the closed set has exactly one source of
+ * truth.
+ */
+export const META_TOOL_ROUTE_SUFFIX: Readonly<Record<MetaToolName, string>> = {
+  [MetaToolName.List]: 'list',
+  [MetaToolName.Describe]: 'describe',
+  [MetaToolName.Invoke]: 'invoke',
+};
+
+// ─── Shared sub-types ───────────────────────────────────────────────────────
+
+/**
+ * Reference to the biome that ships a capability — surfaced on every
+ * `CapabilityListEntry` + `CapabilityDescribeEntry` so the agent can show
+ * provenance ("this tool came from biome X@1.4.0") to the human in the loop.
+ */
+export interface MetaToolBiomeRef {
+  readonly id: string;
+  readonly version: string;
+}
+
+export const MetaToolBiomeRefSchema: z.ZodType<MetaToolBiomeRef> = z.object({
+  id: z.string().min(1),
+  version: z.string().min(1),
+});
+
+// ─── list ───────────────────────────────────────────────────────────────────
+
+/**
+ * Request envelope for `xema.capabilities.list`. The router carries an opaque
+ * `executionContext` payload (validated server-side against
+ * `@xemahq/execution-context-contracts`) so the meta-tool surface and the
+ * grant-cache key on the same shape.
+ */
+export interface CapabilityListRequest {
+  readonly executionContext: Record<string, unknown>;
+  readonly includeDenied?: boolean | undefined;
+}
+
+export const CapabilityListRequestSchema: z.ZodType<CapabilityListRequest> =
+  z.object({
+    executionContext: z.record(z.string(), z.unknown()),
+    includeDenied: z.boolean().optional(),
+  });
+
+/**
+ * Policy decision kinds surfaced on each `CapabilityListEntry`. Mirrors
+ * `@xemahq/policy-contracts/PolicyDecisionKind` value-for-value; we redefine
+ * it here so capability-contracts stays a leaf with no upward kernel deps.
+ */
+export enum MetaToolPolicyDecision {
+  Allow = 'allow',
+  Deny = 'deny',
+  NeedsApproval = 'needs_approval',
+}
+
+export const MetaToolPolicyDecisionSchema = z.nativeEnum(MetaToolPolicyDecision);
+
+export interface CapabilityListEntry {
+  readonly ref: CapabilityRef;
+  readonly biome: MetaToolBiomeRef;
+  readonly title: string;
+  readonly summary: string;
+  readonly riskTier: string;
+  readonly policyDecision: MetaToolPolicyDecision;
+  readonly denialReason?: string | undefined;
+}
+
+export const CapabilityListEntrySchema: z.ZodType<CapabilityListEntry> =
+  z.object({
+    ref: CapabilityRefSchema,
+    biome: MetaToolBiomeRefSchema,
+    title: z.string().min(1),
+    summary: z.string(),
+    riskTier: z.string().min(1),
+    policyDecision: MetaToolPolicyDecisionSchema,
+    denialReason: z.string().optional(),
+  });
+
+export interface CapabilityListResponse {
+  readonly capabilities: readonly CapabilityListEntry[];
+}
+
+export const CapabilityListResponseSchema: z.ZodType<CapabilityListResponse> =
+  z.object({
+    capabilities: z.array(CapabilityListEntrySchema).readonly(),
+  });
+
+// ─── describe ───────────────────────────────────────────────────────────────
+
+/**
+ * Plan-mandated upper bound on the `describe` batch size — agents should
+ * chunk above this. Centralised so the router + clients agree on the same
+ * number.
+ */
+export const META_TOOL_DESCRIBE_BATCH_LIMIT = 50;
+
+export interface CapabilityDescribeRequest {
+  readonly refs: readonly CapabilityRef[];
+}
+
+export const CapabilityDescribeRequestSchema: z.ZodType<CapabilityDescribeRequest> =
+  z.object({
+    refs: z.array(CapabilityRefSchema).min(1).max(META_TOOL_DESCRIBE_BATCH_LIMIT),
+  });
+
+export interface CapabilityDescribeEntry {
+  readonly ref: CapabilityRef;
+  readonly biome: MetaToolBiomeRef;
+  readonly inputSchema: Record<string, unknown>;
+  readonly outputSchema: Record<string, unknown>;
+  readonly examples: readonly Record<string, unknown>[];
+  readonly sideEffects: string;
+  readonly requiresApproval: boolean;
+}
+
+export const CapabilityDescribeEntrySchema: z.ZodType<CapabilityDescribeEntry> =
+  z.object({
+    ref: CapabilityRefSchema,
+    biome: MetaToolBiomeRefSchema,
+    inputSchema: z.record(z.string(), z.unknown()),
+    outputSchema: z.record(z.string(), z.unknown()),
+    examples: z.array(z.record(z.string(), z.unknown())).readonly(),
+    sideEffects: z.string(),
+    requiresApproval: z.boolean(),
+  });
+
+export interface CapabilityDescribeResponse {
+  readonly entries: readonly CapabilityDescribeEntry[];
+}
+
+export const CapabilityDescribeResponseSchema: z.ZodType<CapabilityDescribeResponse> =
+  z.object({
+    entries: z.array(CapabilityDescribeEntrySchema).readonly(),
+  });
+
+// ─── invoke ─────────────────────────────────────────────────────────────────
+
+export interface CapabilityInvokeRequest {
+  readonly ref: CapabilityRef;
+  readonly input: Record<string, unknown>;
+  readonly executionContext: Record<string, unknown>;
+}
+
+export const CapabilityInvokeRequestSchema: z.ZodType<CapabilityInvokeRequest> =
+  z.object({
+    ref: CapabilityRefSchema,
+    input: z.record(z.string(), z.unknown()),
+    executionContext: z.record(z.string(), z.unknown()),
+  });
+
+export interface CapabilityInvokeObligation {
+  readonly kind: string;
+  readonly value?: unknown;
+}
+
+export const CapabilityInvokeObligationSchema: z.ZodType<CapabilityInvokeObligation> =
+  z.object({
+    kind: z.string().min(1),
+    value: z.unknown().optional(),
+  });
+
+export interface CapabilityInvokeResponse {
+  readonly output?: Record<string, unknown> | undefined;
+  readonly auditId: string;
+  readonly obligations: readonly CapabilityInvokeObligation[];
+}
+
+export const CapabilityInvokeResponseSchema: z.ZodType<CapabilityInvokeResponse> =
+  z.object({
+    output: z.record(z.string(), z.unknown()).optional(),
+    auditId: z.string().min(1),
+    obligations: z.array(CapabilityInvokeObligationSchema).readonly(),
+  });

package/src/capability/lib/permission-profile.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import { CapabilityRefSchema, type CapabilityRef } from './capability-ref';
+
+/**
+ * Closed set of built-in permission **Profiles** shipped by the kernel
+ * (plan §30.3). Profiles are pre-canned `GrantPolicy` templates that an
+ * org admin can apply with one click at biome install time.
+ *
+ * Third-party biomes MUST NOT add profiles (would be a privilege-escalation
+ * vector — §30.3). Orgs may add **Custom Profiles** stored in
+ * `authorization-api`, but those are runtime data, not kernel enum values.
+ *
+ * String values are kebab-case so they match the on-wire / on-disk
+ * representation used in biome manifests (`"defaultProfile":
+ * "support-chatbot"`).
+ */
+export enum BiomePermissionProfile {
+  ReadOnlyAssistant = 'read-only-assistant',
+  SupportChatbot = 'support-chatbot',
+  InternalAgent = 'internal-agent',
+  WorkflowRunner = 'workflow-runner',
+  ConnectorBridge = 'connector-bridge',
+  PowerUserDeveloper = 'power-user-developer',
+  OrgAdminTool = 'org-admin-tool',
+  SandboxOnly = 'sandbox-only',
+  Unrestricted = 'unrestricted',
+}
+
+export const BiomePermissionProfileSchema = z.nativeEnum(
+  BiomePermissionProfile,
+);
+
+/**
+ * Risk tier of a single capability ask, declared by the biome author in
+ * the manifest (plan §30.1, §30.2). Drives the install-time digest and
+ * default approval requirements (`critical` always requires explicit
+ * approval, regardless of profile).
+ */
+export enum CapabilityRiskTier {
+  Low = 'low',
+  Medium = 'medium',
+  High = 'high',
+  Critical = 'critical',
+}
+
+export const CapabilityRiskTierSchema = z.nativeEnum(CapabilityRiskTier);
+
+/**
+ * `PermissionHint` — one entry per declared `requiresCapabilities[]` ref
+ * in the biome manifest's `permissions.hints[]` block (plan §30.2).
+ *
+ * The hint is author-facing copy that drives the install-time digest UI;
+ * it does NOT itself grant anything. The grant materialises only when the
+ * admin approves a profile or a custom `GrantPolicy`.
+ *
+ * `suggestedResource` is a glob (often with `${orgId}` / `${projectId}`
+ * placeholders that the install UI substitutes). `suggestedScope` is a
+ * connector-/domain-specific record (e.g. `{ trackerProject: "SUPPORT" }`)
+ * carried verbatim — the kernel does not introspect it.
+ */
+export interface PermissionHint {
+  capability: CapabilityRef;
+  reason: string;
+  suggestedResource?: string;
+  suggestedScope?: Record<string, unknown>;
+  riskTier: CapabilityRiskTier;
+}
+
+export const PermissionHintSchema = z.object({
+  capability: CapabilityRefSchema,
+  reason: z.string().min(1),
+  suggestedResource: z.string().min(1).optional(),
+  suggestedScope: z.record(z.string(), z.unknown()).optional(),
+  riskTier: CapabilityRiskTierSchema,
+}) as z.ZodType<PermissionHint>;
+
+/**
+ * `PermissionGroup` — author-side bundling of related capabilities so the
+ * install UI can render "Grant the *kb-read* group" as one toggle
+ * (plan §30.2). Grants are still recorded per-capability in
+ * `authorization-api`; the group is pure UX sugar.
+ */
+export interface PermissionGroup {
+  name: string;
+  capabilities: readonly CapabilityRef[];
+}
+
+export const PermissionGroupSchema = z.object({
+  name: z.string().min(1),
+  capabilities: z.array(CapabilityRefSchema).readonly(),
+}) as z.ZodType<PermissionGroup>;

package/src/capability/lib/shell-command-descriptor.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { CapabilityRefSchema, type CapabilityRef } from './capability-ref';
+
+/**
+ * Stub for a JSON Schema reference. Modelled as `{ $ref: string }` so
+ * downstream services (notably `xema-shell-api`) can plug in their richer
+ * `JsonSchemaRef` shape without the kernel having to know about JSON Schema
+ * machinery. Phase-1A intentional scope limit.
+ */
+export interface JsonSchemaRefStub {
+  $ref: string;
+}
+
+export const JsonSchemaRefStubSchema = z.object({
+  $ref: z.string().min(1),
+}) as z.ZodType<JsonSchemaRefStub>;
+
+/**
+ * `ShellCommandDescriptor` — plan §31.5. Single source of truth for human
+ * help (`xema help <cmd>`), agent help (the `xema-shell:run@1` self-describe
+ * surface), and the host UI's command palette.
+ *
+ * Kernel-level invariant: `requiredCapabilities` and `relatedConcepts` are
+ * carried as plain strings here. `requiredCapabilities` entries MUST be
+ * valid `CapabilityRef`s and ARE validated by `CapabilityRefSchema`.
+ * `relatedConcepts` carries `XemaObjectRef` strings — kept as plain strings
+ * (validated for non-emptiness only) so this leaf package does not have to
+ * depend on `@xemahq/xema-object-contracts`, which would form a kernel cycle
+ * if `xema-object-contracts` ever needed a `CapabilityRef`.
+ *
+ * `safeForAgents` is enforced by `xema-capability-router` per §31.7 — the
+ * descriptor is the source of truth; the gateway never relaxes it.
+ */
+export interface ShellCommandDescriptor {
+  name: string;
+  summary: string;
+  syntax: string;
+  examples: string[];
+  requiredCapabilities: CapabilityRef[];
+  /**
+   * Environment slugs (e.g. `'project'`, `'sandbox'`). Carried as strings so this
+   * leaf does not pull in `@xemahq/execution-environment-contracts` — the Shell
+   * dispatcher resolves environment refs at runtime.
+   */
+  requiredZones?: string[];
+  /**
+   * `XemaObjectRef` strings (e.g. `'xema://concept/biome'`). Validated only
+   * for non-emptiness here; structural validation lives in
+   * `@xemahq/xema-object-contracts` to avoid a kernel cycle.
+   */
+  relatedConcepts: string[];
+  safeForAgents: boolean;
+  outputSchema?: JsonSchemaRefStub;
+}
+
+export const ShellCommandDescriptorSchema = z.object({
+  name: z.string().min(1),
+  summary: z.string().min(1),
+  syntax: z.string().min(1),
+  examples: z.array(z.string().min(1)),
+  requiredCapabilities: z.array(CapabilityRefSchema),
+  requiredZones: z.array(z.string().min(1)).optional(),
+  relatedConcepts: z.array(z.string().min(1)),
+  safeForAgents: z.boolean(),
+  outputSchema: JsonSchemaRefStubSchema.optional(),
+}) as z.ZodType<ShellCommandDescriptor>;

package/src/contribution/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/contribution-kind';
+export * from './lib/contribution-source';
+export * from './lib/contribution';
+export * from './lib/registry';

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

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+
+/**
+ * `ContributionKind` is the closed enum that names every kind of thing a biome
+ * (biome) may contribute to the Xema OS through the Contribution Protocol
+ * (XSI plane 2). Extending it is a one-line PR to the kernel.
+ *
+ * The seed set is documented in the Xema OS plan-of-record §12.1. Each
+ * additional value below the v1 seed (e.g. `ShellCommand`, `DoctorCheck`) is
+ * pulled from a specific section of the same plan and is cited inline.
+ *
+ * Enum string values match the slug spoken by the rest of the protocol
+ * (Capability References, manifest declarations) so that round-tripping
+ * between the enum and the wire is lossless.
+ */
+export enum ContributionKind {
+  // -- v1 seed (plan §12.1) -------------------------------------------------
+  ConnectorBinding = 'connector-binding',
+  MountSource = 'mount-source',
+  McpTool = 'mcp-tool',
+  DocumentTemplate = 'document-template',
+  DocumentTheme = 'document-theme',
+  WorkflowStep = 'workflow-step',
+  GateAction = 'gate-action',
+  ChartRuntime = 'chart-runtime',
+  PresentationRuntime = 'presentation-runtime',
+  AgentSkill = 'agent-skill',
+  AgentDefinition = 'agent-definition',
+  ModelResolutionDimension = 'model-resolution-dimension',
+  WidgetKind = 'widget-kind',
+
+  // -- Xema Shell additions (plan §31.5 / §31.9) ---------------------------
+  /** A command descriptor contributed to the Xema Shell. Plan §31.5. */
+  ShellCommand = 'shell-command',
+  /** A `xema doctor` health check contributed by a biome. Plan §31.9. */
+  DoctorCheck = 'doctor-check',
+
+  // -- Registry gaps closed (plan §17.12) ----------------------------------
+  /**
+   * An artifact type contributed by a biome to the artifact-store schema-
+   * version registry (`ArtifactTypeRegistryService`). The registry adapter
+   * migration is a separate work item; this member closes the enum gap.
+   */
+  ArtifactType = 'artifact-type',
+  /**
+   * An inquiry kind contributed by a biome to the inquiry-contracts
+   * `InquiryKindSchemaRegistry` (`kind-registry.ts`). The registry adapter
+   * migration is a separate work item; this member closes the enum gap.
+   */
+  InquiryKind = 'inquiry-kind',
+
+  // -- Phase C absorption (plan §6 C.2) ------------------------------------
+  // The Phase-C "Contribution Protocol" rollup is the single source of
+  // truth for every kind of contribution a biome can ship. A biome's
+  // `contributions/` directory replaces the legacy `content/` + `modules/`
+  // seeders. Per-kind handlers are wired through
+  // `BootstrapContributionsService<TKind, TManifest>` (see
+  // `biome-host-sdk/bootstrap-contributions-service.ts`).
+
+  /** A role capability bundle contributed by a biome. */
+  RoleCapability = 'role-capability',
+  /** The biome-install JSON Schema declaration shipped by a biome. */
+  BiomeInstallSchema = 'biome-install-schema',
+  /** A UI icon asset contributed by a biome. */
+  Icon = 'icon',
+  /** A project-kit bundle contributed by a biome. */
+  ProjectKit = 'project-kit',
+  /** A provisioning scaffold contributed by a biome. */
+  ProvisioningScaffold = 'provisioning-scaffold',
+  /** A workspace-spec overlay contributed by a biome. */
+  WorkspaceSpecOverlay = 'workspace-spec-overlay',
+  /** A system-overlay contribution shipped by a biome. */
+  SystemOverlayContribution = 'system-overlay-contribution',
+  /** A concrete integration provider contributed by a biome inside an
+   * adapter kind. */
+  IntegrationProvider = 'integration-provider',
+
+  // Additional content kinds with no direct v3 seed equivalent.
+  /** Workflow-config content shipped by a biome. */
+  WorkflowConfig = 'workflow-config',
+  /** A deliverable-spec contributed by a biome. */
+  DeliverableSpec = 'deliverable-spec',
+  /** A workspace manifest contributed by a biome. */
+  WorkspaceManifest = 'workspace-manifest',
+  /** A workspace-manifest template contributed by a biome. */
+  WorkspaceManifestTemplate = 'workspace-manifest-template',
+  /** A tool-profile contributed by a biome. */
+  ToolProfile = 'tool-profile',
+  /** An MCP catalog entry contributed by a biome. Distinct from `McpTool`,
+   * which is a single tool descriptor; an `McpCatalog` entry is a catalog
+   * manifest. */
+  McpCatalog = 'mcp-catalog',
+  /** An OpenCode tool descriptor contributed by a biome. */
+  OpenCodeTool = 'opencode-tool',
+  /** An OpenCode plugin descriptor contributed by a biome. */
+  OpenCodePlugin = 'opencode-plugin',
+  /** An adapter-kind module contributed by a biome. */
+  AdapterKind = 'adapter-kind',
+  /** A mount-source kind module contributed by a biome. Distinct from
+   * `MountSource`, which registers a concrete mount; `MountSourceKind`
+   * registers the kind itself. */
+  MountSourceKind = 'mount-source-kind',
+  /** A deliverable-spec kind module contributed by a biome. */
+  DeliverableSpecKind = 'deliverable-spec-kind',
+  /** A runtime-mount kind module contributed by a biome. */
+  RuntimeMountKind = 'runtime-mount-kind',
+
+  // -- Phase H#2: capability self-registration (plan §6.H) -----------------
+  /**
+   * A `CapabilityRef` descriptor contributed by a biome — title, summary,
+   * I/O schemas, risk tier, and approval flag. The boot-time codemod
+   * `tooling/codegen/biomes-register-capabilities.mjs` walks every biome's
+   * `contributions/*.capability.contribution.json` (and inline
+   * `xema-biome.json` `contributions.inline[]` entries), validates each
+   * envelope against `CapabilityContributionManifestSchema` from
+   * `@xemahq/capability-contracts`, and emits a per-biome
+   * `register-capabilities.ts` that batch-POSTs them to
+   * `capability-registry-api`. The legacy `INITIAL_CAPABILITY_SEED` in
+   * capability-registry-api stays the authoritative source until every
+   * Wave-1 capability migrates to a biome contribution — both paths
+   * upsert by `ref`, so they cannot drift.
+   */
+  Capability = 'capability',
+}
+
+/**
+ * Zod mirror of `ContributionKind` for runtime validation of envelopes
+ * crossing trust boundaries (HTTP, event payloads, persisted manifests).
+ */
+export const ContributionKindSchema = z.nativeEnum(ContributionKind);
+
+export type ContributionKindValue = `${ContributionKind}`;

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

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+/**
+ * `ContributionSource` is the 5-tier scope at which a Contribution lives.
+ * Value-identical to `SkillSpace` and `CompositionSpace` (see
+ * `.claude/rules/skills-and-composition.md`) — the three enums share ONE
+ * ownership / scope model and must not drift.
+ *
+ * Precedence — **most specific wins**:
+ *
+ *   User > Project > Org > Biome > System
+ *
+ * - `System`  — kernel/platform-shipped; immutable from the UI.
+ * - `Biome`   — contributed by an installed biome.
+ * - `Org`     — authored by an organization.
+ * - `Project` — scoped to a single project.
+ * - `User`    — authored by a single user.
+ */
+export enum ContributionSource {
+  System = 'system',
+  Biome = 'biome',
+  Org = 'org',
+  Project = 'project',
+  User = 'user',
+}
+
+export const ContributionSourceSchema = z.nativeEnum(ContributionSource);
+
+export type ContributionSourceValue = `${ContributionSource}`;