@xemahq/kernel-contracts 0.1.0

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

@@ -0,0 +1,111 @@
+/**
+ * Canonical error codes the LLM Gateway emits when an upstream provider
+ * call fails. Defined in this kernel package so consumers can branch on
+ * the code with a strongly-typed enum and never have to string-match
+ * upstream provider messages themselves.
+ *
+ * The gateway maps each provider's idiosyncratic error shape (OpenAI's
+ * `error.code`, Anthropic's `type`, vLLM's flat `code`) into one of
+ * these values. Adding a new code is a non-breaking change; renaming
+ * one is breaking and requires coordinated updates across consumers.
+ */
+export enum LlmGatewayErrorCode {
+  /**
+   * Upstream rejected the request because the prompt + max_tokens
+   * exceeds the model's context window. Consumers handling agentic
+   * loops should compact the message history and retry.
+   *
+   * Detection signatures:
+   *  - OpenAI: HTTP 400, `error.code === 'context_length_exceeded'`
+   *    or message matches `/maximum context length/i`
+   *  - Anthropic: HTTP 400, `error.type === 'invalid_request_error'`
+   *    + message matches `/input length and max_tokens exceed/i`
+   *  - vLLM: HTTP 400, message matches
+   *    `/maximum context length is \d+ tokens/i`
+   */
+  CONTEXT_LENGTH_EXCEEDED = 'CONTEXT_LENGTH_EXCEEDED',
+  /** Upstream returned 429 (rate limit) or 529 (overloaded). */
+  RATE_LIMITED = 'RATE_LIMITED',
+  /** Upstream blocked the request via content moderation. */
+  CONTENT_FILTERED = 'CONTENT_FILTERED',
+  /** Caller authentication / authorization rejected by upstream. */
+  AUTH_FAILED = 'AUTH_FAILED',
+  /** Model name unknown to the upstream provider. */
+  MODEL_NOT_FOUND = 'MODEL_NOT_FOUND',
+  /** Upstream returned 5xx (transient infrastructure failure). */
+  PROVIDER_UNAVAILABLE = 'PROVIDER_UNAVAILABLE',
+  /** Network or transport-level failure reaching the upstream provider. */
+  PROVIDER_NETWORK = 'PROVIDER_NETWORK',
+  /** Upstream returned an error the gateway could not classify. */
+  UNKNOWN_PROVIDER_ERROR = 'UNKNOWN_PROVIDER_ERROR',
+  /**
+   * The gateway aborted a stream that exceeded `MAX_STREAM_DURATION_MS`.
+   * Partial output may have been forwarded before the abort.
+   */
+  STREAM_DURATION_EXCEEDED = 'STREAM_DURATION_EXCEEDED',
+}
+
+/**
+ * Normalized error envelope. Emitted by llm-gateway-api as either:
+ *  - the body of a non-2xx HTTP response, or
+ *  - an in-stream SSE chunk: `data: {"error": {…}}\n\ndata: [DONE]\n\n`.
+ *
+ * Always carries the canonical code so consumers can branch
+ * deterministically; `httpStatus` and `providerMessage` are diagnostic.
+ */
+export interface LlmGatewayErrorPayload {
+  code: LlmGatewayErrorCode;
+  /** Human-readable message, normalized from the upstream response. */
+  message: string;
+  /**
+   * Original HTTP status returned by the upstream provider (or by the
+   * gateway itself if the failure is transport-level).
+   */
+  httpStatus: number;
+  /** Raw error message from the provider, if available. Diagnostic only. */
+  providerMessage?: string;
+  /** Provider slug (e.g. `qwen-3-5-35b`, `anthropic`). Diagnostic only. */
+  provider?: string;
+}
+
+/**
+ * Wire shape of an in-stream error frame. Distinguished from a normal
+ * Chat Completions chunk by the presence of a top-level `error` field
+ * (Chat Completions chunks always have `choices`).
+ */
+export interface LlmGatewayErrorFrame {
+  error: LlmGatewayErrorPayload;
+}
+
+/**
+ * Type guard for {@link LlmGatewayErrorFrame}.
+ */
+export function isLlmGatewayErrorFrame(value: unknown): value is LlmGatewayErrorFrame {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as { error?: unknown };
+  if (!candidate.error || typeof candidate.error !== 'object') return false;
+  const err = candidate.error as { code?: unknown };
+  return typeof err.code === 'string';
+}
+
+/**
+ * Typed exception thrown by `consumeLlmStream` when the stream
+ * contains an {@link LlmGatewayErrorFrame}. Carries the full payload so
+ * callers can branch on `err.payload.code` rather than inspecting
+ * `instanceof` chains.
+ *
+ * Subclasses are intentionally avoided — adding a new error code does
+ * not require a new class. Callers do `if (err.payload.code === X)`.
+ */
+export class LlmGatewayStreamError extends Error {
+  readonly payload: LlmGatewayErrorPayload;
+
+  constructor(payload: LlmGatewayErrorPayload) {
+    super(`LLM gateway error [${payload.code}]: ${payload.message}`);
+    this.name = 'LlmGatewayStreamError';
+    this.payload = payload;
+    // Restore prototype chain — required when extending Error in TS targets
+    // < ES2022. Safe to leave for forward compatibility.
+    Object.setPrototypeOf(this, LlmGatewayStreamError.prototype);
+  }
+}

package/src/mcp-tool/index.ts

@@ -0,0 +1,6 @@
+export * from './lib/mcp-protocol';
+export * from './lib/mcp-server-config';
+export * from './lib/provider-kind';
+export * from './lib/resolver-scope';
+export * from './lib/tool-provider';
+export * from './lib/tool-selection';

package/src/mcp-tool/lib/mcp-protocol.ts

@@ -0,0 +1,94 @@
+/**
+ * MCP JSON-RPC 2.0 wire types. Subset the unified MCP architecture
+ * speaks with OpenCode (the `remote` transport): `initialize`,
+ * `ping`, `tools/list`, `tools/call`.
+ *
+ * Single source of truth for every layer that produces or consumes
+ * MCP payloads — bridge controller, providers, frontend preview,
+ * SDK helpers. Do NOT duplicate these in any other package.
+ */
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id?: string | number | null;
+  method: string;
+  params?: unknown;
+}
+
+export interface JsonRpcError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  result?: unknown;
+  error?: JsonRpcError;
+}
+
+export const JsonRpcErrorCode = {
+  ParseError: -32700,
+  InvalidRequest: -32600,
+  MethodNotFound: -32601,
+  InvalidParams: -32602,
+  InternalError: -32603,
+  /** MCP: tool-call failed upstream. */
+  ToolInvocationError: -32000,
+  /** MCP: auth config missing or invalid. */
+  AuthMisconfiguration: -32001,
+} as const;
+
+export const McpMethod = {
+  Initialize: 'initialize',
+  ToolsList: 'tools/list',
+  ToolsCall: 'tools/call',
+  Ping: 'ping',
+} as const;
+
+export interface InitializeParams {
+  protocolVersion?: string;
+  capabilities?: Record<string, unknown>;
+  clientInfo?: { name?: string; version?: string };
+}
+
+export interface InitializeResult {
+  protocolVersion: string;
+  capabilities: { tools: { listChanged: boolean } };
+  serverInfo: { name: string; version: string };
+  instructions?: string;
+}
+
+export interface McpTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export interface ToolsListResult {
+  tools: McpTool[];
+}
+
+export interface ToolsCallParams {
+  name: string;
+  arguments?: Record<string, unknown>;
+}
+
+export interface McpTextContent {
+  type: 'text';
+  text: string;
+}
+
+export interface ToolsCallResult {
+  content: McpTextContent[];
+  isError?: boolean;
+  /**
+   * Optional out-of-band metadata that the bridge may attach to a tool-call
+   * result. Callers (UI, workflow steps) can read this for rich surface
+   * rendering (e.g. `surface` carries raw row data for `db_query`/`db_mutate`
+   * that must NOT be forwarded to the LLM).  The field is NOT included in the
+   * JSON-RPC `result` object returned to the agent.
+   */
+  _meta?: Record<string, unknown>;
+}

package/src/mcp-tool/lib/mcp-server-config.ts

@@ -0,0 +1,17 @@
+/**
+ * One MCP server entry as it appears in `opencode.json:mcp`. Produced
+ * by `ToolProvider.buildMcpServerConfig` and returned by the resolver
+ * (`POST /mcp-resolve`). Renderers downstream are dumb — they take
+ * `Record<string, McpServerConfigEntry>` and drop it into the OpenCode
+ * config without any per-kind branching.
+ *
+ * `name` is the safe slug used as the key in `opencode.json:mcp`; it
+ * MUST be a unique value within a single resolver response.
+ */
+export interface McpServerConfigEntry {
+  readonly name: string;
+  readonly type: 'remote';
+  readonly url: string;
+  readonly headers: Record<string, string>;
+  readonly enabled: true;
+}

package/src/mcp-tool/lib/provider-kind.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+
+/**
+ * Closed-but-extensible enum of MCP tool sources the platform knows
+ * how to resolve, sign tokens for, route, and surface in the picker.
+ *
+ * Adding a new kind is a deliberate, audited change: new enum value,
+ * new `ToolProvider` implementation, one new bridge-route pair on the
+ * canonical `/mcp/<kind>/:resourceId` shape, one new branch in the
+ * frontend `<ToolSelectionPicker>`. Resolver, catalog, session boot,
+ * and the OpenCode renderer are all kind-agnostic by construction.
+ */
+export enum ToolProviderKind {
+  /** Org-owned or system-owned MCP server (OpenAPI-bridged or native MCP). */
+  McpServer = 'mcp_server',
+  /** Curated, named bundle of tools spanning multiple providers. */
+  Catalog = 'catalog',
+  /** Biome manifest `xema.mcpWorkflowTools[]` projected as MCP tools. */
+  BiomeWorkflowTools = 'biome_workflow_tools',
+  /**
+   * Biome handler functions decorated with `@BiomeCodeTool` in the
+   * biome's own API service. The platform wraps them as MCP; the
+   * biome never sees MCP protocol.
+   */
+  BiomeCodeTools = 'biome_code_tools',
+  /**
+   * Org-managed Postgres explorer — introspect schemas, run queries and
+   * mutations, trigger and poll Prisma migrations. Resource id is the
+   * `databaseId` from the session briefcase.
+   */
+  OrgDatabaseExplorer = 'org_database_explorer',
+}
+
+/** Runtime zod schema for the enum — used at PATCH/PATCH boundaries. */
+export const toolProviderKindSchema = z.nativeEnum(ToolProviderKind);

package/src/mcp-tool/lib/resolver-scope.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+/**
+ * The (orgId, projectId, sessionId, actor, optional installation) tuple
+ * every resolver call and every bridge dispatch is scoped to.
+ *
+ * Tenancy enforcement: every layer that touches a `ToolSelectionEntry`
+ * MUST validate that the entry's `resourceId` resolves under THIS scope
+ * before granting access. The resolver does it before signing tokens;
+ * the bridge guard re-checks at dispatch by re-fetching the resource
+ * and comparing orgs (defense-in-depth).
+ *
+ * `sessionId` is the OpenCode-facing session/allocation identifier. For
+ * interactive sessions it is `Session.id`; for workflow agents it is
+ * the worker allocation id. Used for workspace-proxy mount-apply
+ * scoping and for bridge-token issuance.
+ */
+export interface ResolverScope {
+  readonly orgId: string;
+  readonly projectId: string;
+  readonly sessionId: string;
+  readonly actorSubject: string | null;
+  readonly installationId?: string;
+}
+
+export const resolverScopeSchema = z.object({
+  orgId: z.string().min(1),
+  projectId: z.string().min(1),
+  sessionId: z.string().min(1),
+  actorSubject: z.string().min(1).nullable(),
+  installationId: z.string().min(1).optional(),
+});

package/src/mcp-tool/lib/tool-provider.ts

@@ -0,0 +1,62 @@
+import type { McpServerConfigEntry } from './mcp-server-config';
+import type { McpTool, ToolsCallResult } from './mcp-protocol';
+import type { ToolProviderKind } from './provider-kind';
+import type { ResolverScope } from './resolver-scope';
+
+/**
+ * Optional narrowing applied when a `ToolSelectionEntry` is of `kind:
+ * 'tool'` — the resolver passes `allowedToolNames` so the provider can
+ * filter `listTools` and the bridge guard can reject `tools/call` for
+ * any name outside this set.
+ */
+export interface ProviderNarrow {
+  readonly allowedToolNames: readonly string[];
+}
+
+export interface CallToolInput {
+  readonly resourceId: string;
+  readonly toolName: string;
+  readonly args: Record<string, unknown> | undefined;
+  readonly scope: ResolverScope;
+  /**
+   * The actor JWT carried in the inbound bridge request, when present.
+   * Required when the provider chains into workspace-proxy mount-apply
+   * (which validates the actor against Keycloak).
+   */
+  readonly actorBearerToken?: string;
+}
+
+/**
+ * Contract every MCP tool source implements. The four current
+ * implementations live in mcp-gateway-api; adding a fifth is one
+ * implementation file + a registry entry + a route pair.
+ *
+ * Tenancy: implementations MUST scope every data access by
+ * `scope.orgId` / `scope.projectId`. The framework re-checks at the
+ * bridge guard but providers are the data-layer defense-in-depth.
+ */
+export interface ToolProvider {
+  readonly kind: ToolProviderKind;
+
+  /** List the tools this resource exposes under the given scope. */
+  listTools(
+    resourceId: string,
+    scope: ResolverScope,
+    narrow?: ProviderNarrow,
+  ): Promise<McpTool[]>;
+
+  /** Invoke one tool. Must be safe under concurrent calls. */
+  callTool(input: CallToolInput): Promise<ToolsCallResult>;
+
+  /**
+   * Build the `opencode.json:mcp` entry that points back to the
+   * gateway's canonical route for this `(kind, resourceId)`. The
+   * `bridgeToken` is already signed with the right scope and narrow.
+   */
+  buildMcpServerConfig(
+    resourceId: string,
+    scope: ResolverScope,
+    bridgeToken: string,
+    narrow?: ProviderNarrow,
+  ): McpServerConfigEntry;
+}

package/src/mcp-tool/lib/tool-selection.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+
+import { ToolProviderKind, toolProviderKindSchema } from './provider-kind';
+
+/**
+ * One unit of tool selection. Either "all tools from this provider"
+ * (`kind: 'provider'`) or "this specific tool" (`kind: 'tool'`).
+ *
+ * `resourceId` is opaque from the kernel's POV — it's the addressable
+ * id of the underlying resource (OrgMcpServer.id, McpToolCatalog.id,
+ * or BiomeInstallation.id) depending on `providerKind`. Cross-org
+ * misuse is blocked at every layer (selection PATCH validation,
+ * resolver scope binding, bridge token scope, data-layer WHERE
+ * clauses) — see `.claude/plans/we-have-integrations-as-swift-haven.md`.
+ *
+ * `toolName` is the canonical MCP tool name as exposed by the
+ * provider's `listTools` (NOT a slug; the value MCP clients invoke).
+ */
+export type ToolSelectionEntry =
+  | {
+      readonly kind: 'provider';
+      readonly providerKind: ToolProviderKind;
+      readonly resourceId: string;
+    }
+  | {
+      readonly kind: 'tool';
+      readonly providerKind: ToolProviderKind;
+      readonly resourceId: string;
+      readonly toolName: string;
+    };
+
+/** Ordered list. Order is preserved end-to-end (affects opencode key ordering). */
+export type ToolSelection = readonly ToolSelectionEntry[];
+
+const baseEntry = z.object({
+  providerKind: toolProviderKindSchema,
+  resourceId: z.string().min(1).max(256),
+});
+
+export const toolSelectionEntrySchema = z.discriminatedUnion('kind', [
+  baseEntry.extend({ kind: z.literal('provider') }),
+  baseEntry.extend({
+    kind: z.literal('tool'),
+    toolName: z.string().min(1).max(256),
+  }),
+]);
+
+export const toolSelectionSchema = z.array(toolSelectionEntrySchema).max(128);

package/src/object/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/xema-object-kind';
+export * from './lib/object-lifecycle';
+export * from './lib/xema-object-ref';
+export * from './lib/xema-object';

package/src/object/lib/object-lifecycle.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+/**
+ * Lifecycle every versioned XemaObject moves through. Mirrors
+ * `CompositionLifecycle` from `@xemahq/agent-composition-contracts` —
+ * the two enums MUST stay value-identical (one ownership model across
+ * the four primitives + every other XemaObject kind, per
+ * `.claude/rules/skills-and-composition.md`).
+ *
+ * - `Draft` — internal revision; never resolved, never installable,
+ *   never referenced by a lockfile.
+ * - `Published` — immutable; the only state resolution serves.
+ * - `Archived` — kept for lineage; never resolved; existing locked
+ *   references keep working.
+ */
+export enum ObjectLifecycle {
+  Draft = 'draft',
+  Published = 'published',
+  Archived = 'archived',
+}
+
+export const ObjectLifecycleSchema = z.nativeEnum(ObjectLifecycle);

package/src/object/lib/xema-object-kind.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+
+/**
+ * Closed enum of every addressable thing in Xema. New kinds are added by
+ * one-line kernel PR — this is intentional: the Object Model is the
+ * canonical typed universe Xema knows about and every platform service,
+ * biome, agent, workflow, and external surface (XSI plane 1) addresses
+ * objects through this enum.
+ *
+ * String values are kebab-case so they slot directly into XemaObjectRef
+ * paths (`xema://<scope-path>/<kind>/<slug>[@<version>]`).
+ */
+export enum XemaObjectKind {
+  // Layer 4-5 — Apps + Audience
+  Biome = 'biome',
+  App = 'app',
+  AppClient = 'app-client',
+  AudiencePolicy = 'audience-policy',
+  ExternalSubject = 'external-subject',
+  DelegatedSession = 'delegated-session',
+
+  // Agent runtime primitives + composition
+  Agent = 'agent',
+  AgentComposition = 'agent-composition',
+  Skill = 'skill',
+  Tool = 'tool',
+  Model = 'model',
+  ModelResolutionRule = 'model-resolution-rule',
+
+  // Workflow + gates
+  Workflow = 'workflow',
+  WorkflowRun = 'workflow-run',
+  GateAction = 'gate-action',
+
+  // Integration / mount / artifact plane
+  Connector = 'connector',
+  ConnectorBinding = 'connector-binding',
+  MountSource = 'mount-source',
+  ArtifactType = 'artifact-type',
+  Artifact = 'artifact',
+
+  // Knowledge + documents
+  KnowledgeSpace = 'knowledge-space',
+  KnowledgePage = 'knowledge-page',
+  DocumentTemplate = 'document-template',
+  DocumentTheme = 'document-theme',
+  ChartRuntime = 'chart-runtime',
+  PresentationRuntime = 'presentation-runtime',
+  WidgetKind = 'widget-kind',
+
+  // Capability + environment + policy
+  Capability = 'capability',
+  ExecutionEnvironment = 'execution-environment',
+  CapabilityGrant = 'capability-grant',
+  ApprovalRule = 'approval-rule',
+
+  // Memory + relations
+  Memory = 'memory',
+  MemoryRelation = 'memory-relation',
+
+  // Session + events
+  Session = 'session',
+  EventStream = 'event-stream',
+  EventSubscription = 'event-subscription',
+
+  // Contribution registry (self-referential)
+  ContributionEntry = 'contribution-entry',
+
+  // Concept registry — self-describing OS documentation objects (§31.3)
+  Concept = 'concept',
+}
+
+export const XemaObjectKindSchema = z.nativeEnum(XemaObjectKind);