@xemahq/kernel-contracts 0.40.0 → 0.42.0

package/src/agent-composition/lib/model-resolution-matrix.ts

@@ -15,7 +15,7 @@
 // boundaries — agent start, sub-agent spawn, and `/skill` launch.
 // ═══════════════════════════════════════════════════════════════════════════
 
-import type { ModelRef } from '../../workflow';
+import type { ModelCapability, ModelRef } from '../../workflow';
 
 /**
  * Open registry of matrix dimensions. v1 ships agent/skill/project/stage;
@@ -34,6 +34,7 @@ export enum ResolutionDimension {
   Stage = 'stage',
   ModelClass = 'modelClass',
   Purpose = 'purpose',
+  ModelCapability = 'modelCapability',
 }
 
 /**
@@ -55,6 +56,14 @@ export interface ModelMatrixSelector {
   readonly stage?: string;
   /** Match when the resolving agent's modelClass equals this value. */
   readonly modelClass?: string;
+  /**
+   * Match when the resolving model's intrinsic capability includes this value
+   * (e.g. route every `vision`-capable invocation to a multimodal model). A
+   * typed, first-class dimension — never routed through `extra`. Closed set
+   * owned by the kernel (`ModelCapability` in
+   * `@xemahq/kernel-contracts/workflow`).
+   */
+  readonly modelCapability?: ModelCapability;
   /**
    * Match when the invocation's non-agent purpose equals this value. Used
    * for system flows that route LLM calls outside the agent/skill model —
@@ -93,6 +102,12 @@ export interface ModelResolutionContext {
    * sites; undefined for non-agent purposes.
    */
   readonly modelClass?: string;
+  /**
+   * The resolving model's intrinsic capability — populated at agent-invocation
+   * build sites when the routing needs a capability-gated model; undefined
+   * otherwise. Matched against `ModelMatrixSelector.modelCapability`.
+   */
+  readonly modelCapability?: ModelCapability;
   /**
    * Non-agent invocation purpose (e.g. memory summarization/embedding).
    * Optional — agent and skill invocations leave this undefined.

package/src/connector/lib/canonical-operation-binding.ts

@@ -24,7 +24,7 @@ import { z } from 'zod';
 import {
   CanonicalObjectTypeRefSchema,
   type CanonicalObjectTypeRef,
-} from '../../canonical-object/lib/canonical-object-type';
+} from '../../canonical-object';
 
 /** Which way a bound operation maps between provider records and canonical objects. */
 export enum CanonicalMappingDirection {

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

@@ -283,6 +283,24 @@ export enum ContributionKind {
    * point. Provenance (`biome.id/version`) is stamped by the parser.
    */
   CanonicalObjectType = 'canonical-object-type',
+
+  // -- External-source ingestion plane ---------------------------------------
+  /**
+   * Category 1 (biome-host `KindParser`). A PULL-BASED EXTERNAL DATA SOURCE a
+   * biome declares so the platform can materialize an external dataset into a
+   * local catalog on a cadence, with change-detection and provenance. The
+   * descriptor is pure data — WHERE the data comes from (`fetch`), HOW OFTEN to
+   * pull (`cadence`), HOW to tell it changed (`changeDetection`), and WHERE the
+   * pulled records land (`catalog`) — never any mint/transform code. The kernel
+   * owns this member AND the manifest schema
+   * (`IngestionSourceContributionManifestSchema`, exported from
+   * `@xemahq/kernel-contracts/ingestion-source`), mirroring the `Capability` /
+   * `SearchType` / `CanonicalObjectType` kinds: one value-identical wire shape
+   * validated fail-fast by BOTH the biome-host parser and the owning ingestion
+   * service. Provenance (`biome.id/version`) is stamped by the parser — never
+   * declared inline.
+   */
+  IngestionSource = 'ingestion-source',
 }
 
 /**

package/src/enterprise-context/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/context-document';
+export * from './lib/context-mount-entry';
+export * from './lib/dropped-context';
+export * from './lib/context-bundle';

package/src/enterprise-context/lib/context-bundle.ts

@@ -0,0 +1,35 @@
+import type { ContextDocument } from './context-document';
+import type { ContextMountEntry } from './context-mount-entry';
+import type { DroppedContextDocument } from './dropped-context';
+
+/**
+ * The assembled Enterprise-Context bundle — the result of retrieving and
+ * ranking documents about a canonical object and packing them into a
+ * budget-bounded, materialisable mount plan.
+ *
+ * The bundle is producer-neutral: the first producer is
+ * connector-gateway-api's enterprise-context module, but the shape is a
+ * kernel contract so any assembler and any consumer (e.g. an agent-session
+ * launch that materialises the mount plan) agree on the wire.
+ *
+ * `primary` is the canonical entity echoed back verbatim (the retrieval
+ * subject), serialised into the first `static-literal` mount entry. It is
+ * the raw object, not a ranked {@link ContextDocument}. `documents` are the
+ * ranked retrieval hits; `mountPlan` materialises the entity plus every
+ * document that fit the budget; `dropped` lists documents excluded by the
+ * budget. `bytesUsed` is the total content bytes actually placed in the
+ * mount plan and never exceeds `byteBudget`.
+ */
+export interface ContextBundle {
+  /** The canonical object type this bundle was assembled for. */
+  readonly objectType: string;
+  /** The canonical entity echoed back (the retrieval subject). */
+  readonly primary?: Readonly<Record<string, unknown>>;
+  readonly documents: readonly ContextDocument[];
+  readonly mountPlan: readonly ContextMountEntry[];
+  readonly dropped: readonly DroppedContextDocument[];
+  /** Total content-byte budget applied while packing the mount plan. */
+  readonly byteBudget: number;
+  /** Total content bytes materialised in the mount plan (≤ `byteBudget`). */
+  readonly bytesUsed: number;
+}

package/src/enterprise-context/lib/context-document.ts

@@ -0,0 +1,23 @@
+/**
+ * One retrieved, ranked document included in an assembled
+ * {@link ContextBundle}. Sourced from a search/retrieval pass over the
+ * canonical-object corpus; `score` is the fused relevance (max across
+ * retrieval passes).
+ *
+ * `content` is the retrieved body (a summary/snippet when the retrieval
+ * pass does not return full content). It is the same string materialised
+ * as the document's `static-literal` mount bytes when the document fits
+ * the byte budget.
+ */
+export interface ContextDocument {
+  /** Stable document reference, e.g. `kb_page:src_abc123`. */
+  readonly ref: string;
+  /** Document type discriminator, e.g. `kb_page`. */
+  readonly docType: string;
+  readonly title?: string;
+  readonly summary?: string;
+  /** Retrieved content (summary/snippet when full content is unavailable). */
+  readonly content?: string;
+  /** Fused relevance score (max across retrieval passes). */
+  readonly score: number;
+}

package/src/enterprise-context/lib/context-mount-entry.ts

@@ -0,0 +1,29 @@
+import type { MountSource } from '../../workflow';
+
+/**
+ * Access mode of a context mount entry. Assembled enterprise context is
+ * never written by the agent, so the mode is closed to `read-only`.
+ *
+ * Modelled as a single-value closed type (const + `typeof` type) rather
+ * than a two-member enum: the domain today has exactly one legal value and
+ * a wider mode would misrepresent the contract. A future read-write context
+ * mode is a deliberate contract change, not an open string.
+ */
+export const CONTEXT_MOUNT_MODE = 'read-only' as const;
+
+export type ContextMountMode = typeof CONTEXT_MOUNT_MODE;
+
+/**
+ * One materialisable mount entry in an assembled {@link ContextBundle}.
+ *
+ * `source` is the full kernel {@link MountSource} discriminated union — not
+ * narrowed to the `static-literal` variant the first producer
+ * (connector-gateway-api) emits — so future producers can attach other
+ * kinds (e.g. `kb-pages`) without a contract change. The session's
+ * mount-apply pipeline materialises every entry as a typed mount, so the
+ * assembled context lands under `/workspace/` as real files.
+ */
+export interface ContextMountEntry {
+  readonly mode: ContextMountMode;
+  readonly source: MountSource;
+}

package/src/enterprise-context/lib/dropped-context.ts

@@ -0,0 +1,24 @@
+/**
+ * Why a retrieved document was excluded from an assembled
+ * {@link ContextBundle}. Closed set — a dropped document is always
+ * reported (never silently discarded), and the reason is a typed enum so
+ * consumers can branch on it without string matching.
+ *
+ * Today the only exclusion path is the byte-budget cap applied while
+ * charging ranked documents against the bundle's `byteBudget`. New
+ * exclusion reasons extend this enum (one member) — do not introduce a
+ * free-form reason string.
+ */
+export enum DroppedContextReason {
+  /** Adding the document's content would exceed the bundle byte budget. */
+  BYTE_BUDGET_EXCEEDED = 'BYTE_BUDGET_EXCEEDED',
+}
+
+/** A document excluded from the bundle — reported, never silently dropped. */
+export interface DroppedContextDocument {
+  /** Stable document reference of the excluded document. */
+  readonly ref: string;
+  /** Content byte-size that would have been added had it been included. */
+  readonly bytes: number;
+  readonly reason: DroppedContextReason;
+}

package/src/ingestion-source/index.ts

@@ -0,0 +1,20 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/kernel-contracts/ingestion-source — external-source ingestion
+// contribution contract.
+//
+// Pure types + Zod schemas for the `ContributionKind.IngestionSource` manifest:
+// the declarative, boot-time registration of a PULL-BASED external data source
+// a biome contributes so the platform materializes an external dataset into a
+// local catalog on a cadence, with change-detection and provenance. The
+// manifest is pure data — WHERE (`fetch`), HOW OFTEN (`cadence`), HOW-CHANGED
+// (`changeDetection`), WHERE-IT-LANDS (`catalog`) — never mint/transform code
+// and never a secret. Self-contained: zero cross-subpath edges, zero runtime
+// deps beyond `zod`.
+//
+// NOTE: this is distinct from `search-source` (runtime `IndexableDocument`,
+// event-fed document INSTANCES) and from `search` (search RESULT-TYPES). An
+// ingestion source is the CONTRIBUTED (declarative, boot-time) declaration of a
+// pull-based origin; the records it yields flow to their catalog at runtime.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/ingestion-source-contribution';

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

@@ -0,0 +1,238 @@
+import { z } from 'zod';
+
+/**
+ * Maximum length of the short identifier / label / tag strings on an ingestion
+ * source manifest. Bounded so list/describe responses stay small and persisted
+ * rows have a predictable upper size.
+ */
+const INGESTION_SOURCE_STRING_MAX = 200;
+
+/**
+ * Maximum length of the free-text summary. A summary is a one-liner, not a
+ * document.
+ */
+const INGESTION_SOURCE_SUMMARY_MAX = 1000;
+
+/**
+ * Maximum length of a fetch URL / cadence expression / record selector — each
+ * is a small path/pattern, never a document.
+ */
+const INGESTION_SOURCE_URL_MAX = 2000;
+const INGESTION_SOURCE_EXPRESSION_MAX = 200;
+const INGESTION_SOURCE_SELECTOR_MAX = 500;
+
+/** Hard cap on the number of static request headers a source may declare. */
+const INGESTION_SOURCE_HEADERS_MAX = 50;
+
+/**
+ * HTTP method used to pull from an ingestion source. Closed set — a source
+ * either GETs a resource or POSTs a query body.
+ */
+export enum IngestionFetchMethod {
+  GET = 'GET',
+  POST = 'POST',
+}
+
+export const INGESTION_FETCH_METHOD_VALUES: readonly IngestionFetchMethod[] = [
+  IngestionFetchMethod.GET,
+  IngestionFetchMethod.POST,
+];
+
+export const IngestionFetchMethodSchema = z.enum(
+  INGESTION_FETCH_METHOD_VALUES as readonly [
+    IngestionFetchMethod,
+    ...IngestionFetchMethod[],
+  ],
+);
+
+/**
+ * How the pull cadence is expressed. Closed set: a fixed interval or a cron
+ * expression. The `expression` field carries the concrete value (a duration
+ * string for `interval`, a cron string for `cron`).
+ */
+export enum IngestionCadenceKind {
+  INTERVAL = 'interval',
+  CRON = 'cron',
+}
+
+export const INGESTION_CADENCE_KIND_VALUES: readonly IngestionCadenceKind[] = [
+  IngestionCadenceKind.INTERVAL,
+  IngestionCadenceKind.CRON,
+];
+
+export const IngestionCadenceKindSchema = z.enum(
+  INGESTION_CADENCE_KIND_VALUES as readonly [
+    IngestionCadenceKind,
+    ...IngestionCadenceKind[],
+  ],
+);
+
+/**
+ * How the platform decides a pulled resource CHANGED since the last pull.
+ * Closed set — the source declares which signal is authoritative so the puller
+ * never guesses.
+ */
+export enum IngestionChangeDetectionStrategy {
+  /** Compare the HTTP `ETag` response header. */
+  ETAG = 'etag',
+  /** Compare the HTTP `Last-Modified` response header. */
+  LAST_MODIFIED = 'last-modified',
+  /** Hash the fetched body and compare content hashes. */
+  CONTENT_HASH = 'content-hash',
+}
+
+export const INGESTION_CHANGE_DETECTION_STRATEGY_VALUES: readonly IngestionChangeDetectionStrategy[] =
+  [
+    IngestionChangeDetectionStrategy.ETAG,
+    IngestionChangeDetectionStrategy.LAST_MODIFIED,
+    IngestionChangeDetectionStrategy.CONTENT_HASH,
+  ];
+
+export const IngestionChangeDetectionStrategySchema = z.enum(
+  INGESTION_CHANGE_DETECTION_STRATEGY_VALUES as readonly [
+    IngestionChangeDetectionStrategy,
+    ...IngestionChangeDetectionStrategy[],
+  ],
+);
+
+/**
+ * `IngestionFetchSpec` — WHERE the data comes from and HOW to request it. A
+ * plain HTTP pull descriptor: URL, method, and optional static headers. No
+ * credential is carried inline — a private source references a broker-resolved
+ * credential through the platform, never a secret in the manifest.
+ */
+export interface IngestionFetchSpec {
+  /** Absolute URL to pull from. ≤ 2000 chars. */
+  readonly url: string;
+  /** HTTP method. Absent ⇒ `GET`. */
+  readonly method?: IngestionFetchMethod;
+  /** Static request headers (non-secret). Hard-capped at 50 entries. */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+export const IngestionFetchSpecSchema: z.ZodType<IngestionFetchSpec> = z.object({
+  url: z.string().min(1).max(INGESTION_SOURCE_URL_MAX),
+  method: IngestionFetchMethodSchema.optional(),
+  headers: z
+    .record(
+      z.string().min(1).max(INGESTION_SOURCE_STRING_MAX),
+      z.string().max(INGESTION_SOURCE_STRING_MAX),
+    )
+    .refine((h) => Object.keys(h).length <= INGESTION_SOURCE_HEADERS_MAX, {
+      message: `at most ${INGESTION_SOURCE_HEADERS_MAX} headers`,
+    })
+    .optional(),
+}) as z.ZodType<IngestionFetchSpec>;
+
+/**
+ * `IngestionCadenceSpec` — HOW OFTEN the source is pulled. `kind` selects the
+ * grammar; `expression` carries the concrete value.
+ */
+export interface IngestionCadenceSpec {
+  readonly kind: IngestionCadenceKind;
+  /** Interval duration (for `interval`) or cron expression (for `cron`). */
+  readonly expression: string;
+}
+
+export const IngestionCadenceSpecSchema: z.ZodType<IngestionCadenceSpec> =
+  z.object({
+    kind: IngestionCadenceKindSchema,
+    expression: z.string().min(1).max(INGESTION_SOURCE_EXPRESSION_MAX),
+  }) as z.ZodType<IngestionCadenceSpec>;
+
+/**
+ * `IngestionChangeDetectionSpec` — HOW the puller decides a resource changed.
+ */
+export interface IngestionChangeDetectionSpec {
+  readonly strategy: IngestionChangeDetectionStrategy;
+}
+
+export const IngestionChangeDetectionSpecSchema: z.ZodType<IngestionChangeDetectionSpec> =
+  z.object({
+    strategy: IngestionChangeDetectionStrategySchema,
+  }) as z.ZodType<IngestionChangeDetectionSpec>;
+
+/**
+ * `IngestionCatalogSpec` — WHERE pulled records land and how they are tagged
+ * for provenance. `targetIndex` is the local catalog/index the records are
+ * written into; `provenanceTag` stamps each record so a downstream reader can
+ * trace it back to this source.
+ */
+export interface IngestionCatalogSpec {
+  /** The local catalog/index pulled records are written into. ≤ 200 chars. */
+  readonly targetIndex: string;
+  /** Provenance tag stamped on every pulled record. ≤ 200 chars. */
+  readonly provenanceTag: string;
+}
+
+export const IngestionCatalogSpecSchema: z.ZodType<IngestionCatalogSpec> =
+  z.object({
+    targetIndex: z.string().min(1).max(INGESTION_SOURCE_STRING_MAX),
+    provenanceTag: z.string().min(1).max(INGESTION_SOURCE_STRING_MAX),
+  }) as z.ZodType<IngestionCatalogSpec>;
+
+/**
+ * Manifest shape carried by every `ContributionKind.IngestionSource` envelope.
+ * One contribution = one PULL-BASED external data source.
+ *
+ * Mirrors `CapabilityContributionManifest` / `SearchTypeContributionManifest`
+ * precisely: a value-identical subset of the wire body the owning ingestion
+ * service accepts, validated fail-fast at biome-discovery time. Provenance
+ * (`biome.id`, `biome.version`) is NOT a field here — the parser stamps it from
+ * the discovering biome's `xema-biome.json`. Authors do not declare provenance
+ * inline.
+ *
+ * The descriptor is pure DATA: it declares WHERE the data comes from
+ * (`fetch`), HOW OFTEN to pull it (`cadence`), HOW to detect change
+ * (`changeDetection`), WHERE records land (`catalog`), and OPTIONALLY how to
+ * extract records from the fetched body (`recordSelector`). It never carries
+ * transform/mint code and never carries a secret.
+ *
+ * Validation is fail-fast: a contribution that violates any constraint is
+ * rejected at boot. No silent coercion.
+ */
+export interface IngestionSourceContributionManifest {
+  /** Stable identifier for this source within its owning biome. ≤ 200 chars. */
+  readonly sourceKey: string;
+  /** Human-readable source title. ≤ 200 chars. */
+  readonly title: string;
+  /** Optional one-line summary. ≤ 1000 chars. */
+  readonly summary?: string;
+  /** WHERE the data comes from and HOW to request it. */
+  readonly fetch: IngestionFetchSpec;
+  /** HOW OFTEN the source is pulled. */
+  readonly cadence: IngestionCadenceSpec;
+  /** HOW the puller decides a resource changed since the last pull. */
+  readonly changeDetection: IngestionChangeDetectionSpec;
+  /** WHERE pulled records land and how they are tagged for provenance. */
+  readonly catalog: IngestionCatalogSpec;
+  /**
+   * Optional JSONPath-ish selector applied to the fetched body to extract the
+   * record array. Absent ⇒ the whole body is treated as a single record.
+   * ≤ 500 chars.
+   */
+  readonly recordSelector?: string;
+}
+
+/**
+ * Zod validator for `IngestionSourceContributionManifest`. The biome-discovery
+ * parser AND the owning ingestion service's contribution-sync handler BOTH
+ * route every candidate envelope through this schema, so a malformed
+ * contribution fails at the boundary instead of at the wire (mirrors
+ * `CapabilityContributionManifestSchema`).
+ */
+export const IngestionSourceContributionManifestSchema: z.ZodType<IngestionSourceContributionManifest> =
+  z.object({
+    sourceKey: z.string().min(1).max(INGESTION_SOURCE_STRING_MAX),
+    title: z.string().min(1).max(INGESTION_SOURCE_STRING_MAX),
+    summary: z.string().min(1).max(INGESTION_SOURCE_SUMMARY_MAX).optional(),
+    fetch: IngestionFetchSpecSchema,
+    cadence: IngestionCadenceSpecSchema,
+    changeDetection: IngestionChangeDetectionSpecSchema,
+    catalog: IngestionCatalogSpecSchema,
+    recordSelector: z
+      .string()
+      .min(1)
+      .max(INGESTION_SOURCE_SELECTOR_MAX)
+      .optional(),
+  }) as z.ZodType<IngestionSourceContributionManifest>;

package/src/llm-gateway/lib/errors.ts

@@ -77,6 +77,52 @@ export interface LlmGatewayErrorFrame {
   error: LlmGatewayErrorPayload;
 }
 
+/**
+ * Message signatures that identify a context-window overflow when NO typed
+ * {@link LlmGatewayErrorCode} survived to the consumer.
+ *
+ * The authoritative provider-message → code classification lives in
+ * llm-gateway-api's `upstream-error-classifier.ts` (an independent submodule
+ * that cannot import this kernel package). This list is the CONSUMER-side
+ * counterpart: when an agentic runtime (e.g. OpenCode) swallows the gateway's
+ * typed code and re-surfaces only a human-readable string, this is the single
+ * place a consumer recognizes the overflow. Keep the two lists in parity when
+ * a new provider phrasing appears.
+ */
+export const CONTEXT_OVERFLOW_MESSAGE_PATTERNS: readonly RegExp[] = [
+  /maximum context length is \d+ tokens/i,
+  /input length and max_tokens exceed context limit/i,
+  /context_length_exceeded/i,
+  /context window/i,
+  /prompt is too long/i,
+  /reduce the length of (?:the )?messages/i,
+  /exceed(?:s|ed)?\b[^.]{0,40}\bcontext/i,
+];
+
+/**
+ * Deterministically decide whether an error signal is a context-window
+ * overflow — the single well-named predicate every consumer uses instead of
+ * an ad-hoc string match. Prefers the TYPED code
+ * ({@link LlmGatewayErrorCode.CONTEXT_LENGTH_EXCEEDED}); falls back to the
+ * centralized {@link CONTEXT_OVERFLOW_MESSAGE_PATTERNS} ONLY when the code did
+ * not survive to the consumer (e.g. a runtime that forwards a raw message).
+ *
+ * Passing NEITHER a code nor a message returns `false` — never a silent true.
+ */
+export function isContextOverflowError(input: {
+  code?: string | null;
+  message?: string | null;
+}): boolean {
+  if (input.code === LlmGatewayErrorCode.CONTEXT_LENGTH_EXCEEDED) {
+    return true;
+  }
+  const message = input.message;
+  if (typeof message !== 'string' || message.length === 0) {
+    return false;
+  }
+  return CONTEXT_OVERFLOW_MESSAGE_PATTERNS.some((p) => p.test(message));
+}
+
 /**
  * Type guard for {@link LlmGatewayErrorFrame}.
  */

package/src/output/index.ts

@@ -13,6 +13,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 
 export * from './lib/output-kind';
+export * from './lib/point-of-attention';
 export * from './lib/output-render-hint';
 export * from './lib/output-deliverable-expectation';
 export * from './lib/output-version-dto';

package/src/output/lib/output-version-dto.ts

@@ -1,3 +1,5 @@
+import type { PointOfAttention } from './point-of-attention';
+
 /**
  * One row in the version history of an output. The Outputs panel
  * renders a dropdown when `versions.length > 1`; clicking a non-current
@@ -18,4 +20,11 @@ export interface OutputVersionDto {
   readonly producerAgentSlug: string | null;
   /** True when this row is the latest version. Exactly one row has this set. */
   readonly isCurrent: boolean;
+  /**
+   * Generic producer-authored highlights for THIS version — the salient
+   * things a reader should notice (an assumption, a gap, a risk). Optional
+   * extensibility escape hatch so the fixed version schema stays open without
+   * a per-domain field. Absent/empty ⇒ nothing flagged.
+   */
+  readonly pointsOfAttention?: readonly PointOfAttention[];
 }

package/src/output/lib/point-of-attention.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+
+/**
+ * Bounded maxes for the short label / longer detail strings on a point of
+ * attention. Kept small so a version row carrying a handful of them stays a
+ * cheap, list-safe payload.
+ */
+const POINT_OF_ATTENTION_LABEL_MAX = 200;
+const POINT_OF_ATTENTION_DETAIL_MAX = 2000;
+
+/**
+ * Severity of a {@link PointOfAttention}. Closed set — a consumer renders each
+ * value with a fixed badge/colour, so the domain must never be a free-form
+ * string.
+ */
+export enum PointOfAttentionSeverity {
+  /** Neutral highlight — worth surfacing, no action implied. */
+  INFO = 'info',
+  /** Something the reader should scrutinise before relying on the artifact. */
+  WARNING = 'warning',
+  /** A blocking concern — the artifact should not be trusted/acted on as-is. */
+  CRITICAL = 'critical',
+}
+
+export const POINT_OF_ATTENTION_SEVERITY_VALUES: readonly PointOfAttentionSeverity[] =
+  [
+    PointOfAttentionSeverity.INFO,
+    PointOfAttentionSeverity.WARNING,
+    PointOfAttentionSeverity.CRITICAL,
+  ];
+
+/**
+ * Zod schema for {@link PointOfAttentionSeverity}. Built from the enum so the
+ * literal list lives in exactly one place.
+ */
+export const PointOfAttentionSeveritySchema = z.enum(
+  POINT_OF_ATTENTION_SEVERITY_VALUES as readonly [
+    PointOfAttentionSeverity,
+    ...PointOfAttentionSeverity[],
+  ],
+);
+
+/**
+ * A GENERIC "point of attention" / highlight attached to a per-version
+ * artifact. This is the deliberate extensibility escape hatch that keeps a
+ * fixed artifact schema open: a producer can flag the salient things a reader
+ * should notice (an assumption made, a gap, a risk) WITHOUT the kernel growing
+ * a domain-specific field for each. Domain-agnostic — carries only a label, a
+ * detail, and a {@link PointOfAttentionSeverity}; the meaning is the
+ * producer's, never the kernel's.
+ */
+export interface PointOfAttention {
+  /** Short headline for the point (≤ 200 chars). */
+  readonly label: string;
+  /** Longer human-readable explanation (≤ 2000 chars). */
+  readonly detail: string;
+  /** How much scrutiny this point warrants. */
+  readonly severity: PointOfAttentionSeverity;
+}
+
+/**
+ * Zod validator for {@link PointOfAttention}. Fail-fast: a malformed point is
+ * rejected at the boundary rather than silently coerced.
+ */
+export const PointOfAttentionSchema: z.ZodType<PointOfAttention> = z.object({
+  label: z.string().min(1).max(POINT_OF_ATTENTION_LABEL_MAX),
+  detail: z.string().min(1).max(POINT_OF_ATTENTION_DETAIL_MAX),
+  severity: PointOfAttentionSeveritySchema,
+}) as z.ZodType<PointOfAttention>;

package/src/worker-runtime/index.ts

@@ -12,4 +12,5 @@ export * from './lib/capabilities';
 export * from './lib/messages';
 export * from './lib/runtime';
 export * from './lib/runtime-layout-profile';
+export * from './lib/workspace-sandbox';
 export * from './lib/schemas';

package/src/worker-runtime/lib/enums.ts

@@ -26,6 +26,35 @@ export enum WorkerRuntimeKind {
   Hermes = 'hermes',
 }
 
+/**
+ * How a runtime consumes a per-skill "slash command" launcher file, if at
+ * all. Closed set — a runtime that grows a new command surface adds a member
+ * here and the composer/proxy switch exhaustively on it.
+ *
+ * The platform composes ONE per-skill launch command (markdown body with a
+ * `$ARGUMENTS` placeholder) so typing `/<skill>` loads + applies that skill.
+ * WHETHER and in WHICH FORMAT a runtime reads that file differs:
+ *
+ * - `Markdown` — the runtime reads markdown command files from its
+ *   `commandsDir` (OpenCode: `.opencode/{command,commands}/**.md`; Claude
+ *   Code: `.claude/commands/*.md`). Xema emits the launcher for these.
+ * - `Toml` — the runtime's custom commands are TOML, NOT markdown (Qwen).
+ *   Xema does NOT synthesise TOML skill launchers — skills launch via the
+ *   runtime's own `/skills <name>` surface / model-invoked skill tool — so
+ *   the platform emits NOTHING for a TOML runtime rather than a file the
+ *   runtime silently ignores.
+ * - `None` — the runtime has no file-based slash-command surface at all
+ *   (Hermes: `commandsDir` is `null`). Emit nothing.
+ *
+ * Only `Markdown` runtimes receive a materialised per-skill command file;
+ * `Toml`/`None` receive none (never a stray, silently-ignored file).
+ */
+export enum RuntimeCommandFormat {
+  Markdown = 'markdown',
+  Toml = 'toml',
+  None = 'none',
+}
+
 /**
  * Lifecycle hook surfaces that a runtime may support. The set is closed —
  * adding a new hook is a kernel change.