@xemahq/kernel-contracts 0.5.1 → 0.6.0

package/src/agent-composition/lib/capability-layer.ts

@@ -1,7 +1,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 // ── CapabilityLayer ──
 //
-// The capability envelope attached to an Agent Composition: what the
+// The capability envelope attached to an Agent: what the
 // composition is allowed to do at runtime (write policy, repo access,
 // knowledge-base writes, allowed Xema-namespaced tools).
 //
@@ -16,30 +16,30 @@
  * - `own-pages-only`: may only write declared deliverable files.
  * - `full-write`: may write anywhere the workspace permits.
  */
-export const COMPOSITION_WRITE_POLICIES = [
+export const AGENT_WRITE_POLICIES = [
   'read-only',
   'own-pages-only',
   'full-write',
 ] as const;
-export type CompositionWritePolicy =
-  (typeof COMPOSITION_WRITE_POLICIES)[number];
+export type AgentWritePolicy =
+  (typeof AGENT_WRITE_POLICIES)[number];
 
 /**
  * Repo-write capability.
  * - `never`: blanket deny repo writes.
  * - `when-granted`: repo writes allowed iff the dispatch supplied repo slugs.
  */
-export const COMPOSITION_REPO_POLICIES = ['never', 'when-granted'] as const;
-export type CompositionRepoPolicy =
-  (typeof COMPOSITION_REPO_POLICIES)[number];
+export const AGENT_REPO_POLICIES = ['never', 'when-granted'] as const;
+export type AgentRepoPolicy =
+  (typeof AGENT_REPO_POLICIES)[number];
 
 /**
  * The capability envelope of a composition node. Resolved into each
  * invocation's `context.json` authority block.
  */
 export interface CapabilityLayer {
-  readonly writePolicy: CompositionWritePolicy;
-  readonly mayEditRepos: CompositionRepoPolicy;
+  readonly writePolicy: AgentWritePolicy;
+  readonly mayEditRepos: AgentRepoPolicy;
   readonly mayWriteKnowledgeBase: boolean;
   /** Closed allowlist of Xema-namespaced tools (e.g. `xema_memory_set`). */
   readonly allowedXemaTools: readonly string[];

package/src/agent-composition/lib/composition-limits-schema.ts

@@ -1,5 +1,5 @@
 // ═══════════════════════════════════════════════════════════════════════════
-// ── CompositionLimits — Zod schema ──
+// ── AgentLimits — Zod schema ──
 //
 // Validates the runtime envelope a coordinator-style composition node
 // declares on itself (and inherits to descendants). Used by:
@@ -19,16 +19,16 @@
 
 import { z } from 'zod';
 
-import type { CompositionLimits } from './composition';
+import type { AgentLimits } from './composition';
 
 /**
- * Zod schema for {@link CompositionLimits}. Structural counters
+ * Zod schema for {@link AgentLimits}. Structural counters
  * (`maxDepth` / `maxFanout` / `maxSpawns`) are strict positive integers.
  * `tokenBudget` is optional; when omitted, the enforcer treats it as
  * unlimited (no token-budget check). Authors who want NO enforcement at
  * all must omit the entire `limits` block.
  */
-export const CompositionLimitsSchema: z.ZodType<CompositionLimits> = z
+export const AgentLimitsSchema: z.ZodType<AgentLimits> = z
   .object({
     maxDepth: z.number().int().positive(),
     maxFanout: z.number().int().positive(),

package/src/agent-composition/lib/composition-workspace.ts

@@ -1,20 +1,20 @@
 // ═══════════════════════════════════════════════════════════════════════════
-// ── Composition Workspace block ──
+// ── Agent Workspace block ──
 //
 // The AUTHORED source of the workspace's filesystem-layout / persistence /
-// environment configuration. A `Composition` arms an agent with skills +
-// tools (the recursive `CompositionNode` tree); the `workspace` block
+// environment configuration. A `Agent` arms an agent with skills +
+// tools (the recursive `AgentNode` tree); the `workspace` block
 // declares the SHAPE of `/workspace/` that agent runs inside —
 // persist-paths, env vars, and the live output-surface.
 //
 // `WorkspaceSpec` (`@xemahq/agent-workspace-contracts`) is a DERIVED
-// projection: the resolution service projects `Composition.workspace`
+// projection: the resolution service projects `Agent.workspace`
 // onto the resolved `WorkspaceSpec` so workspace-tree consumers read one
 // resolved spec without re-resolving the composition.
 //
 // This block absorbs the layout/persistence/env portion of the retiring
 // `WorkspaceManifest` — the agent/skill/tool-selection portion already
-// moved to `CompositionNode`. Templates (the manifest's Handlebars
+// moved to `AgentNode`. Templates (the manifest's Handlebars
 // seed-files) become skill-bundle resources served by skill-registry-api,
 // so they are NOT modelled here.
 // ═══════════════════════════════════════════════════════════════════════════
@@ -43,7 +43,7 @@ export type {
  * target and emit one gateway route per app — used by webapp studios
  * that scaffold N apps under one composition.
  */
-export enum CompositionOutputSurfaceMode {
+export enum AgentOutputSurfaceMode {
   Single = 'single',
   Multi = 'multi',
 }
@@ -68,14 +68,14 @@ export enum CompositionOutputSurfaceMode {
  *   - `app` / `tunnel`: reserved for future surface kinds; field set
  *     mirrors `web`.
  */
-export interface CompositionOutputSurface {
+export interface AgentOutputSurface {
   readonly kind: OutputSurfaceKind;
   readonly port?: number;
   readonly healthPath?: string;
   /** Auto-open the preview pane on first ready signal. */
   readonly autoOpen?: boolean;
   /** Single-port (default) vs. multi-app output surface. */
-  readonly mode?: CompositionOutputSurfaceMode;
+  readonly mode?: AgentOutputSurfaceMode;
   /**
    * Workspace-relative directory served as a static site. Required and
    * only meaningful when `kind === 'static'`. The DSL schema enforces
@@ -92,7 +92,7 @@ export interface CompositionOutputSurface {
 
 /**
  * The agent run-config the composer needs that is NOT carried by the
- * `CompositionNode` tree. The node tree pins WHICH agent runs; these
+ * `AgentNode` tree. The node tree pins WHICH agent runs; these
  * three fields pin the run FRAMING (stage + role + deliverable
  * contract) the renderer + system-overlay are driven by.
  *
@@ -102,7 +102,7 @@ export interface CompositionOutputSurface {
  * the workspace pipeline resolves against the run's bind inputs (the
  * same fail-fast interpolation grammar `env` values use).
  */
-export interface CompositionAgentRunConfig {
+export interface AgentRunConfig {
   readonly stage: string;
   readonly role: AgentRunRole;
   readonly deliverableSpecRef?: string;
@@ -135,7 +135,7 @@ export interface CompositionAgentRunConfig {
  * fragments with the DSL's `WorkspaceManifestSchema` when it
  * reconstructs + compiles the manifest.
  */
-export interface CompositionMountLayout {
+export interface AgentMountLayout {
   /**
    * Raw `spec.mounts` block — user-data mount declarations keyed by AWP
    * slot key. Each value is the manifest DSL `ManifestMountDeclaration`
@@ -144,7 +144,7 @@ export interface CompositionMountLayout {
    */
   readonly mounts: Readonly<Record<string, unknown>>;
   /** Agent run-config (stage + role + deliverable contract). */
-  readonly agentRunConfig: CompositionAgentRunConfig;
+  readonly agentRunConfig: AgentRunConfig;
   /**
    * Raw `spec.seedFiles` array — manifest DSL `ManifestSeedFile`
    * entries (`{ path, slot?, template?, content?, vars? }`). `vars` may
@@ -162,12 +162,12 @@ export interface CompositionMountLayout {
 }
 
 /**
- * Authored workspace-layout config carried on a `Composition`. Every
+ * Authored workspace-layout config carried on a `Agent`. Every
  * field is optional + additive — a composition that declares no
  * `workspace` block produces a `WorkspaceSpec` with no projected
  * `persistence` / `env` (the AWP base slots still apply).
  */
-export interface CompositionWorkspace {
+export interface AgentWorkspaceConfig {
   /**
    * Workspace-relative persist-paths + per-slot policy overrides.
    * Authoritative SOURCE projected onto `WorkspaceSpec.persistence`.
@@ -184,15 +184,15 @@ export interface CompositionWorkspace {
    * Output-surface declaration. Optional — omitted for
    * compositions that do not expose an output surface.
    */
-  readonly outputSurface?: CompositionOutputSurface;
+  readonly outputSurface?: AgentOutputSurface;
   /**
    * The user-data mount layout — which AWP slots the profile enables,
    * per-slot mode, the agent run-config, and seed files. The residual
-   * the Agent Composition primitive absorbed from `WorkspaceManifest`
+   * the Agent primitive absorbed from `WorkspaceManifest`
    * in Phase 10, Step 3d. Optional + additive — a composition with no
    * `mountLayout` runs on the AWP base slots alone with no seed files.
    */
-  readonly mountLayout?: CompositionMountLayout;
+  readonly mountLayout?: AgentMountLayout;
   /**
    * Working files the platform materialises for this session.
    *
@@ -226,7 +226,7 @@ export interface CompositionWorkspace {
    * manifest. Same seed → compose → resolve path as {@link credentials};
    * consumed by the environment resolver + resume drift detection.
    * Optional + additive. Distinct from the per-node
-   * {@link CompositionNode.permission} overlay — this is the workspace
+   * {@link AgentNode.permission} overlay — this is the workspace
    * toolset policy, not the agent's permission map. Was silently DROPPED
    * at seed before (BUG-1).
    */

package/src/agent-composition/lib/composition.ts

@@ -1,5 +1,5 @@
 // ═══════════════════════════════════════════════════════════════════════════
-// ── Agent Composition ──
+// ── Agent ──
 //
 // The recursive "workflow-as-agent" primitive: an Agent armed with Skills
 // and Tools, whose sub-agents are themselves fully-armed composition nodes
@@ -18,12 +18,12 @@ import type { NodeOverlayFragment } from '../../workflow';
 import type { SkillRef } from '../../skill';
 import type { BiomeAvailabilityScoped } from '../../biome-availability';
 import type { CapabilityLayer } from './capability-layer';
-import type { CompositionWorkspace } from './composition-workspace';
+import type { AgentWorkspaceConfig } from './composition-workspace';
 
 /**
  * A stable reference to an agent definition, optionally version-pinned.
  */
-export interface AgentRef {
+export interface AgentKernelRef {
   readonly slug: string;
   /** Pinned version; omitted = latest. */
   readonly version?: string;
@@ -34,7 +34,7 @@ export interface AgentRef {
  * is reusable. Mirrors `SkillSpace`; compositions are org-scoped so they
  * are authored once and reused across projects.
  */
-export enum CompositionSpace {
+export enum AgentSpace {
   System = 'system',
   Biome = 'biome',
   Org = 'org',
@@ -48,7 +48,7 @@ export enum CompositionSpace {
  * - `published`: immutable; the only state resolution will serve.
  * - `archived`: retired; kept for lineage but never resolved.
  */
-export enum CompositionLifecycle {
+export enum AgentLifecycle {
   Draft = 'draft',
   Published = 'published',
   Archived = 'archived',
@@ -64,7 +64,7 @@ export enum CompositionLifecycle {
  * declares the budget once and the whole subtree shares it.
  *
  * **Breach semantics — IMPORTANT:** any breach aborts the SSE stream and
- * throws a non-retryable `ApplicationFailure(COMPOSITION_BUDGET_EXCEEDED)`.
+ * throws a non-retryable `ApplicationFailure(AGENT_BUDGET_EXCEEDED)`.
  * The activity ends without emitting a deliverable; the harvester never
  * runs. All in-flight work is lost — HITL re-dispatches from the prior
  * gate. This is the right semantics for *structural* runaways (depth /
@@ -76,7 +76,7 @@ export enum CompositionLifecycle {
  * unlimited. `maxDepth` / `maxFanout` / `maxSpawns` are the load-bearing
  * structural caps.
  */
-export interface CompositionLimits {
+export interface AgentLimits {
   /** Recursion depth ceiling — root = depth 0, first sub-agent = 1, etc. */
   readonly maxDepth: number;
   /** Concurrent `task()` spawns allowed per node within a single turn. */
@@ -100,11 +100,11 @@ export interface CompositionLimits {
  * `skills` / `tools` / `modelOverride` attach AT this node — they extend or
  * override what the referenced agent definition declares intrinsically.
  */
-export interface CompositionNode
+export interface AgentNode
   extends NodeOverlayFragment,
     BiomeAvailabilityScoped {
   /** The agent definition this node runs. */
-  readonly agent: AgentRef;
+  readonly kernel: AgentKernelRef;
   /** Optional alias when the same agent appears more than once in the tree. */
   readonly alias?: string;
   /** Skills attached at this node. */
@@ -116,7 +116,7 @@ export interface CompositionNode
   // OVERRIDE the model, APPEND to the base prompt, and RESTRICT-merge the
   // permission for this node only.
   /** Sub-agents — themselves fully-armed composition nodes (recursive). */
-  readonly children: readonly CompositionNode[];
+  readonly children: readonly AgentNode[];
   /**
    * Hard budget the runtime enforces against `task()` spawn telemetry
    * for THIS node and every descendant it produces at runtime. Inherited
@@ -124,22 +124,22 @@ export interface CompositionNode
    * limits once at the root. Absent root + absent descendants = no
    * enforcement (today's pre-coordinator workflows).
    */
-  readonly limits?: CompositionLimits;
+  readonly limits?: AgentLimits;
 }
 
 /**
- * A named, versioned, reusable Agent Composition.
+ * A named, versioned, reusable Agent.
  */
-export interface Composition {
+export interface Agent {
   /** Stable slug; the identity within the registry. */
   readonly slug: string;
   readonly version: string;
   readonly displayName: string;
   readonly description?: string;
-  readonly scope: CompositionSpace;
-  readonly lifecycle: CompositionLifecycle;
+  readonly scope: AgentSpace;
+  readonly lifecycle: AgentLifecycle;
   /** The root (primary) agent node. */
-  readonly root: CompositionNode;
+  readonly root: AgentNode;
   /** Capability envelope applied to the composition at runtime. */
   readonly capability?: CapabilityLayer;
   /**
@@ -150,23 +150,23 @@ export interface Composition {
    * alone. Absorbs the layout/persistence/env portion of the retiring
    * `WorkspaceManifest`.
    */
-  readonly workspace?: CompositionWorkspace;
+  readonly workspace?: AgentWorkspaceConfig;
 }
 
 /**
  * The flattened, runtime-facing form of one resolved composition node.
- * The resolution service produces this tree from a stored `Composition`;
+ * The resolution service produces this tree from a stored `Agent`;
  * the workspace/composer pipeline consumes it. Sub-agent nodes appear
  * as `children` (still recursive) — each child is itself fully armed.
  *
- * Distinct from `CompositionNode` (the AUTHORED form): a resolved node
+ * Distinct from `AgentNode` (the AUTHORED form): a resolved node
  * has its agent reference fully version-pinned, never `latest`.
  */
-export interface ResolvedCompositionNode
+export interface ResolvedAgentNode
   extends NodeOverlayFragment,
     BiomeAvailabilityScoped {
   /** Fully version-pinned agent reference. */
-  readonly agent: Required<AgentRef>;
+  readonly kernel: Required<AgentKernelRef>;
   readonly alias?: string;
   /** Skill references attached at this node (version-pinned). */
   readonly skills: readonly SkillRef[];
@@ -177,28 +177,28 @@ export interface ResolvedCompositionNode
   // composer layers instructions onto the base systemPrompt and deep-merges
   // permission over the agent's authored permission before the system tiers.
   /** Resolved sub-agent nodes (recursive). */
-  readonly children: readonly ResolvedCompositionNode[];
+  readonly children: readonly ResolvedAgentNode[];
   /**
    * Resolved budget for this node. The resolver propagates the nearest
-   * declared `limits` from the source `CompositionNode` (root usually
+   * declared `limits` from the source `AgentNode` (root usually
    * carries it; descendants inherit). Absent = no enforcement on this
    * node and its descendants — preserves today's pre-coordinator
    * workflow behaviour where no budget was declared.
    */
-  readonly limits?: CompositionLimits;
+  readonly limits?: AgentLimits;
 }
 
 /**
  * The resolution service's output: a composition resolved against a task
  * context, ready for the composer/workspace pipeline to consume.
  */
-export interface ResolvedComposition {
+export interface ResolvedAgent {
   readonly slug: string;
   readonly version: string;
   readonly displayName: string;
-  readonly scope: CompositionSpace;
+  readonly scope: AgentSpace;
   /** Resolved root node — the primary agent. */
-  readonly root: ResolvedCompositionNode;
+  readonly root: ResolvedAgentNode;
   /** Capability envelope applied to the whole composition at runtime. */
   readonly capability: CapabilityLayer;
   /**
@@ -207,5 +207,5 @@ export interface ResolvedComposition {
    * interpolation in `env` values is already resolved here. The
    * workspace pipeline projects this onto the run's `WorkspaceSpec`.
    */
-  readonly workspace?: CompositionWorkspace;
+  readonly workspace?: AgentWorkspaceConfig;
 }

package/src/agent-composition/lib/invocation-overlay.ts

@@ -18,7 +18,7 @@
 //   - skills        : ADD-only   (identity skills are the floor)
 //
 // Agent SELECTION (which agent runs) is deliberately NOT part of this overlay:
-// in a workflow that is `agentSlug`/`agentRef`, and `compositionRef` selects a
+// in a workflow that is `agentSlug` (short form); `agentRef` selects a published Agent
 // workspace SOURCE, not the agent (see plan audit A5). The overlay only SHAPES
 // the already-selected agent.
 // ═══════════════════════════════════════════════════════════════════════════

package/src/agent-workspace/lib/working-file.ts

@@ -123,7 +123,7 @@ export type WorkingFileSourceKind = string;
 
 /**
  * Resolved working-file declaration projected onto the WorkspaceSpec and
- * carried into the session bundle. Composition authors declare the
+ * carried into the session bundle. Agent authors declare the
  * authored shape (with `${input.x}` templating); resolution produces this
  * concrete form with the bind inputs interpolated.
  *

package/src/agent-workspace/lib/workspace-spec.ts

@@ -147,7 +147,7 @@ export interface SlotDefinition {
 /**
  * Workspace-relative paths captured on session pause and restored on
  * resume, plus per-slot policy overrides. The authoritative SOURCE of
- * these values is the authored `Composition.workspace.persistence` block
+ * these values is the authored `Agent.workspace.persistence` block
  * (`@xemahq/agent-composition-contracts`); they are projected onto
  * `WorkspaceSpec` so workspace-tree consumers (session lifecycle,
  * workspace-proxy snapshot pipeline) read them off one resolved spec
@@ -185,7 +185,7 @@ export interface WorkspaceSpec {
   readonly slots: readonly SlotDefinition[];
   /**
    * Workspace-relative persist-paths + per-slot policy overrides.
-   * Projected from `Composition.workspace.persistence`. Optional — when
+   * Projected from `Agent.workspace.persistence`. Optional — when
    * absent the workspace persists only what the slots' own
    * `persistencePolicy` fields declare. Additive: pre-existing consumers
    * that never read this field keep compiling.
@@ -193,7 +193,7 @@ export interface WorkspaceSpec {
   readonly persistence?: WorkspacePersistenceSpec;
   /**
    * Environment variables applied to the agent runtime before dispatch.
-   * Projected from `Composition.workspace.env`. Optional / additive —
+   * Projected from `Agent.workspace.env`. Optional / additive —
    * absent means the composition declared no env block.
    */
   readonly env?: readonly WorkspaceEnvVar[];

package/src/biome-availability/lib/biome-availability.ts

@@ -1,10 +1,10 @@
 // ═══════════════════════════════════════════════════════════════════════════
 // ── Biome Availability Filter — per-definition opt-in/opt-out (DBM.2) ──
 //
-// A definition (an Agent Composition node, an Agent definition, a workflow
+// A definition (an Agent node, an Agent definition, a workflow
 // job, a Session) MAY declare which biomes' contributions it wants in or out.
 // This is a POST-SCOPE FILTER applied AFTER implicit-by-scope resolution
-// (the 5-tier `SkillScope`/`CompositionScope` precedence): it NARROWS the
+// (the 5-tier `SkillScope`/`AgentSpace` precedence): it NARROWS the
 // already-visible set; it never widens it and it is NOT a parallel
 // availability/binding table (see `.claude/rules/skills-and-composition.md`).
 //
@@ -54,7 +54,7 @@ export interface BiomeAvailabilityFilter {
 
 /**
  * The shape a definition mixes in to gain the optional biome opt-in/opt-out
- * knob. Mixed into `CompositionNode`, the Agent definition contract, the
+ * knob. Mixed into `AgentNode`, the Agent definition contract, the
  * workflow job/stage contract, and the Session shape so the field has ONE
  * declaration site (no per-shape restating).
  */

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

@@ -25,7 +25,7 @@ export enum ContributionKind {
   ChartRuntime = 'chart-runtime',
   PresentationRuntime = 'presentation-runtime',
   AgentSkill = 'agent-skill',
-  AgentDefinition = 'agent-definition',
+  AgentKernel = 'agent-kernel',
   ModelResolutionDimension = 'model-resolution-dimension',
   WidgetKind = 'widget-kind',
 

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

@@ -2,7 +2,7 @@ import { z } from 'zod';
 
 /**
  * `ContributionSource` is the 5-tier scope at which a Contribution lives.
- * Value-identical to `SkillSpace` and `CompositionSpace` (see
+ * Value-identical to `SkillSpace` and `AgentSpace` (see
  * `.claude/rules/skills-and-composition.md`) — the three enums share ONE
  * ownership / scope model and must not drift.
  *

package/src/distribution/lib/distribution.ts

@@ -53,7 +53,7 @@ export const DistributionPlatformServiceSchema = z.object({
  * is deployed (the deployment plane). It contains PACKAGING fields only — no
  * infra/deploy/values config (that lives in the deployment overlay).
  *
- * Composition: `extends` names a parent distribution; the resolver composes
+ * Agent: `extends` names a parent distribution; the resolver composes
  * parent → child, with the child's `include`/`exclude` overriding. The resolver
  * enforces (fail-fast): kernel-tier biomes are always included and cannot be
  * excluded; an included biome whose `requires` are absent is an error; selectors

package/src/document-templates/lib/document-template.ts

@@ -51,7 +51,7 @@ export enum DocumentTemplateScope {
  * not interpret the strings, just hands them to skill-registry-api.
  *
  * `subAgents` are agent slugs delegated as sub-agents on the session's
- * Agent Composition. The bar for declaring one is "needs its own model,
+ * Agent. The bar for declaring one is "needs its own model,
  * tools, or context"; most templates leave this empty and rely on
  * sub-skills (cheap, shared context).
  *

package/src/invocation/lib/execution-requirements.ts

@@ -10,7 +10,7 @@ import {
  * Per-invocation hard limits. None are required at the contract level; an
  * absent field means "no caller-declared limit on this axis" (the platform may
  * still apply its own). These map directly onto the existing `composition.limits`
- * consumed by `CompositionBudgetEnforcer` — no new enforcement engine.
+ * consumed by `AgentBudgetEnforcer` — no new enforcement engine.
  */
 export interface InvocationLimits {
   readonly maxDurationMs?: number;

package/src/invocation/lib/invocation-mode.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 /**
- * How the Composition Invocation Runtime executes an invocation.
+ * How the Agent Invocation Runtime executes an invocation.
  *
  * The platform owns mode selection (deterministic `selectMode`): a biome MAY
  * hint a mode via `ExecutionRequirements.mode`, but policy may override it.

package/src/invocation/lib/invocation-record.ts

@@ -16,7 +16,7 @@ import {
  */
 export interface InvocationRecord {
   readonly id: string;
-  readonly compositionRef: string;
+  readonly agentRef: string;
   readonly orgId: string;
   readonly projectId: string | null;
   readonly threadKey: string;
@@ -38,7 +38,7 @@ export interface InvocationRecord {
 
 export const InvocationRecordSchema = z.object({
   id: z.string().min(1),
-  compositionRef: z.string().min(1),
+  agentRef: z.string().min(1),
   orgId: z.string().min(1),
   projectId: z.string().min(1).nullable(),
   threadKey: z.string().min(1),

package/src/invocation/lib/invoke-request.ts

@@ -8,12 +8,12 @@ import {
  * The wire body for `composition:invoke@1` — what a caller sends through the
  * capability funnel to execute a published composition.
  *
- * `CompositionInvokeRequestSchema` is the fail-fast validator the runtime
+ * `AgentInvokeRequestSchema` is the fail-fast validator the runtime
  * applies at the wire boundary before any execution.
  */
-export interface CompositionInvokeRequest {
-  /** Composition slug or `slug@version`. */
-  readonly compositionRef: string;
+export interface AgentInvokeRequest {
+  /** Agent slug or `slug@version`. */
+  readonly agentRef: string;
   readonly orgId: string;
   readonly projectId?: string;
   /** Stable execution-context key — org+mailbox+emailThreadId for mail. */
@@ -23,12 +23,12 @@ export interface CompositionInvokeRequest {
   readonly requirements: ExecutionRequirements;
 }
 
-export const CompositionInvokeRequestSchema = z.object({
-  compositionRef: z.string().min(1),
+export const AgentInvokeRequestSchema = z.object({
+  agentRef: z.string().min(1),
   orgId: z.string().min(1),
   projectId: z.string().min(1).optional(),
   threadKey: z.string().min(1),
   correlationId: z.string().min(1).optional(),
   input: z.record(z.string(), z.unknown()),
   requirements: ExecutionRequirementsSchema,
-}) as z.ZodType<CompositionInvokeRequest>;
+}) as z.ZodType<AgentInvokeRequest>;

package/src/invocation/lib/invoke-response.ts

@@ -13,7 +13,7 @@ import {
  * `Event` mode `output` is omitted and the consumer subscribes to the result
  * completion event instead.
  */
-export interface CompositionInvokeResponse {
+export interface AgentInvokeResponse {
   readonly invocationId: string;
   readonly status: InvocationStatus;
   readonly mode: InvocationMode;
@@ -26,7 +26,7 @@ export interface CompositionInvokeResponse {
   readonly auditId?: string;
 }
 
-export const CompositionInvokeResponseSchema = z.object({
+export const AgentInvokeResponseSchema = z.object({
   invocationId: z.string().min(1),
   status: InvocationStatusSchema,
   mode: InvocationModeSchema,
@@ -36,4 +36,4 @@ export const CompositionInvokeResponseSchema = z.object({
   durationMs: z.number().optional(),
   modelRef: z.string().min(1).optional(),
   auditId: z.string().min(1).optional(),
-}) as z.ZodType<CompositionInvokeResponse>;
+}) as z.ZodType<AgentInvokeResponse>;

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

@@ -2,7 +2,7 @@ import { z } from 'zod';
 
 /**
  * Lifecycle every versioned XemaObject moves through. Mirrors
- * `CompositionLifecycle` from `@xemahq/agent-composition-contracts` —
+ * `AgentLifecycle` 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`).

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

@@ -19,9 +19,9 @@ export enum XemaObjectKind {
   ExternalSubject = 'external-subject',
   DelegatedSession = 'delegated-session',
 
-  // Agent runtime primitives + composition
+  // Agent runtime primitives — a base kernel armed into an Agent
+  AgentKernel = 'agent-kernel',
   Agent = 'agent',
-  AgentComposition = 'agent-composition',
   Skill = 'skill',
   Tool = 'tool',
   Model = 'model',

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

@@ -35,11 +35,11 @@ export const SubjectRefSchema = z.object({
  * - `ref` is the wire-stable address (`XemaObjectRef`).
  * - `kind` is the closed `XemaObjectKind` enum value.
  * - `scope` is the 5-tier ownership reference (single ownership model
- *   shared with `SkillSpace` / `CompositionSpace`).
+ *   shared with `SkillSpace` / `AgentSpace`).
  * - `owner` is the subject that owns the object.
  * - `version` is a semver string. Resolution serves only `Published`
  *   versions per `ObjectLifecycle` semantics.
- * - `lifecycle` mirrors `CompositionLifecycle` (draft/published/archived).
+ * - `lifecycle` mirrors `AgentLifecycle` (draft/published/archived).
  * - `payload` is kind-specific; the resolved schema is supplied by the
  *   owning domain contract package.
  */

package/src/workflow/lib/compiled-run.ts

@@ -14,9 +14,9 @@ import type { WorkflowVariableRequirement } from './variable-requirement';
  * Pre-resolved manifest source for `xema/agent`-shaped jobs. The
  * workflow-dsl compiler emits exactly one variant per agent step:
  *
- *   • `ref` — long-form `with.compositionRef: <slug>` (or
+ *   • `ref` — long-form `with.agentRef: <slug>` (or
  *     `<slug>@<version>`) that the activity resolves at boot via
- *     llm-registry-api's Agent Composition `GET /compositions/resolve/
+ *     llm-registry-api's Agent `GET /compositions/resolve/
  *     :ref`, reconstructing the compiled workspace manifest from the
  *     resolved composition's `workspace.mountLayout` block.
  *   • `inline` — short-form `with.mounts` whose agent metadata
@@ -30,7 +30,7 @@ import type { WorkflowVariableRequirement } from './variable-requirement';
  *
  * `null` for non-agent actions (compileManifestSource short-circuits
  * when the action manifest's `inputs.properties` lacks both
- * `compositionRef` and `mounts`).
+ * `agentRef` and `mounts`).
  */
 export type CompiledManifestSource =
   | { readonly kind: 'ref'; readonly ref: string }