@cjhyy/code-shell-core 0.8.11 → 0.8.12

package/dist/composition/resolve-preset.js

@@ -0,0 +1,58 @@
+import { ConfigError } from "../exceptions.js";
+/** Resolve a preset by name (or the composition default), failing loud. */
+export function resolvePresetFromComposition(composition, name) {
+    const resolvedName = name || composition.engine.defaultPreset;
+    const found = composition.engine.presets.find((p) => p.key === resolvedName);
+    if (found)
+        return found.value;
+    const allowed = composition.engine.presets.map((p) => p.key).join(", ");
+    throw new Error(`Unknown agent preset "${resolvedName}". Available presets: ${allowed}`);
+}
+/** All preset-tags tools — the composed catalog in effective order. */
+export function compositionToolCatalog(composition) {
+    return composition.engine.tools.flatMap((t) => (t.kind === "preset-tags" ? [t.tool] : []));
+}
+/**
+ * Preset-tags tools force-joined to the ACTIVE preset regardless of its name.
+ * Rule: tools owned by modules that contribute no presets (pet-style catalog
+ * tools) — presets snapshot their tool lists from catalogs known at module
+ * authoring time, which can never include such packages. Modules that DO
+ * contribute presets (core, coding) reference their tools via preset tags
+ * already. Visibility stays gated by each tool's exposure.availability.
+ */
+export function presetInjectedTools(composition) {
+    const presetOwners = new Set(composition.engine.presets.map((p) => p.moduleId));
+    return composition.engine.tools.flatMap((t) => t.kind === "preset-tags" && !presetOwners.has(t.moduleId) ? [t.tool] : []);
+}
+/** Module-contributed named prompt sections as a plain record. */
+export function compositionPromptSections(composition) {
+    return Object.fromEntries(composition.engine.promptSections.map((s) => [s.key, s.value]));
+}
+/**
+ * Register always-exposure tools on the engine-local registry fork.
+ * Cross-module uniqueness is compiler-enforced; this guards collisions with
+ * runtime-registered tools.
+ */
+export function registerAlwaysTools(composition, registry) {
+    for (const contribution of composition.engine.tools) {
+        if (contribution.kind !== "always")
+            continue;
+        const name = contribution.tool.definition.name;
+        if (registry.hasTool(name)) {
+            throw new ConfigError(`Capability tool conflicts with registered tool: ${name}`, {
+                duplicateCapabilityTool: name,
+                capabilityId: contribution.moduleId,
+            });
+        }
+        registry.registerTool(contribution.tool.definition, contribution.tool.execute);
+    }
+}
+/** First non-null module instruction boundary, in module order. */
+export function resolveCompositionInstructionBoundary(composition, cwd) {
+    for (const boundary of composition.engine.instructionBoundaries) {
+        const found = boundary.value(cwd);
+        if (found)
+            return found;
+    }
+    return null;
+}

package/dist/composition/snapshot.d.ts

@@ -0,0 +1,9 @@
+import type { CompositionSnapshot, ResolvedComposition } from "./types.js";
+/**
+ * Pure-data projection of a composition. Field construction order is the
+ * canonical serialization order — computeCompositionDigest() hashes the
+ * JSON directly, so never reorder fields without updating golden fixtures.
+ * Unkeyed by design: the snapshot carries no secrets (design §11.2).
+ */
+export declare function toCompositionSnapshot(composition: Pick<ResolvedComposition, "modules" | "engine" | "protocol">): CompositionSnapshot;
+export declare function computeCompositionDigest(snapshot: CompositionSnapshot): string;

package/dist/composition/snapshot.js

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+/**
+ * Pure-data projection of a composition. Field construction order is the
+ * canonical serialization order — computeCompositionDigest() hashes the
+ * JSON directly, so never reorder fields without updating golden fixtures.
+ * Unkeyed by design: the snapshot carries no secrets (design §11.2).
+ */
+export function toCompositionSnapshot(composition) {
+    return {
+        version: 1,
+        modules: composition.modules.map((m) => ({ id: m.id, order: m.order, source: m.source })),
+        tools: composition.engine.tools.map((t) => ({
+            name: t.tool.definition.name,
+            moduleId: t.moduleId,
+            exposure: t.kind,
+            presetTags: t.kind === "preset-tags" ? [...t.tool.exposure.presetTags] : [],
+        })),
+        presets: composition.engine.presets.map((p) => ({
+            name: p.key,
+            moduleId: p.moduleId,
+            isDefault: p.key === composition.engine.defaultPreset,
+        })),
+        promptSections: composition.engine.promptSections.map((s) => ({
+            name: s.key,
+            moduleId: s.moduleId,
+        })),
+        hooks: composition.engine.hooks.map((h) => ({
+            event: h.event,
+            name: h.name,
+            priority: h.priority,
+            moduleId: h.moduleId,
+        })),
+        behaviorProfiles: composition.engine.behaviorProfiles.map((p) => ({
+            id: p.key,
+            moduleId: p.moduleId,
+        })),
+        queries: composition.protocol.queries.map((q) => ({ type: q.key, moduleId: q.moduleId })),
+        observers: composition.protocol.observerFactories.map((o) => o.moduleId),
+        runValidators: composition.protocol.runValidators.map((v) => v.moduleId),
+        hiddenSessionKinds: composition.protocol.hiddenSessionKinds.map((k) => ({
+            kind: k.key,
+            moduleId: k.moduleId,
+        })),
+    };
+}
+export function computeCompositionDigest(snapshot) {
+    return createHash("sha256").update(JSON.stringify(snapshot)).digest("hex");
+}

package/dist/composition/types.d.ts

@@ -0,0 +1,169 @@
+/**
+ * AgentModule — the single trusted product-module interface that unifies
+ * CapabilityModule and ExtensionModule (design:
+ * docs/todo/agent-module-resolved-composition-design.md). Phase A only adds
+ * the types and the pure compiler; no production path consumes them yet.
+ */
+import type { CapabilityArtifactDetector, CapabilityDynamicContextProvider, CapabilityEngineHookContribution, CapabilityFileHistoryContribution, CapabilityInstructionBoundaryFinder, CapabilityToolSelectionContext, CapabilityToolServiceHost, SessionWorkspaceCapability } from "../capabilities/index.js";
+import type { AgentPreset } from "../preset/index.js";
+import type { BuiltinTool } from "../tool-system/builtin/index.js";
+import type { ExtensionQueryHandler, ExtensionTool, ProtocolObserver, ProtocolObserverHost } from "../tool-system/capability-module.js";
+import type { RunBehaviorProfile } from "../engine/run-types.js";
+import type { HookEventName } from "../hooks/events.js";
+/**
+ * One tool contribution with explicit exposure:
+ * - "preset-tags": full BuiltinTool metadata; joins the composed catalog.
+ * - "always": plain ExtensionTool; registered directly, always visible.
+ */
+export type AgentModuleToolContribution = {
+    readonly kind: "preset-tags";
+    readonly tool: BuiltinTool;
+} | {
+    readonly kind: "always";
+    readonly tool: ExtensionTool;
+};
+export interface AgentEngineContributions {
+    readonly tools?: readonly AgentModuleToolContribution[];
+    readonly presets?: readonly AgentPreset[];
+    /** Preset used when the host does not choose one. At most one module may declare it. */
+    readonly defaultPreset?: string;
+    readonly promptSections?: Readonly<Record<string, string>>;
+    readonly dynamicContextProviders?: readonly CapabilityDynamicContextProvider[];
+    readonly instructionBoundary?: CapabilityInstructionBoundaryFinder;
+    readonly artifactDetectors?: readonly CapabilityArtifactDetector[];
+    readonly fileHistory?: readonly CapabilityFileHistoryContribution[];
+    readonly sessionWorkspace?: SessionWorkspaceCapability;
+    readonly hooks?: readonly CapabilityEngineHookContribution[];
+    readonly behaviorProfiles?: readonly RunBehaviorProfile[];
+    readonly adjustToolSelection?: (names: Set<string>, context: CapabilityToolSelectionContext) => void;
+    /** Phase C renames this to privateService with owned lifetime. */
+    readonly createToolService?: (host: CapabilityToolServiceHost) => unknown;
+}
+export interface AgentProtocolContributions {
+    readonly queries?: Readonly<Record<string, ExtensionQueryHandler>>;
+    /** Existing name createProtocolObserver; renamed here by design. */
+    readonly createObserver?: (host: ProtocolObserverHost) => ProtocolObserver;
+    readonly validateRunParams?: (params: Record<string, unknown>) => string | null;
+    readonly hiddenSessionKinds?: readonly string[];
+}
+export interface AgentModule {
+    readonly id: string;
+    readonly engine?: AgentEngineContributions;
+    readonly protocol?: AgentProtocolContributions;
+}
+export interface ResolvedModule {
+    readonly id: string;
+    readonly order: number;
+    readonly source: "core" | "host";
+}
+export interface ResolvedContribution<T> {
+    readonly key: string;
+    readonly moduleId: string;
+    readonly value: T;
+}
+export type ResolvedToolContribution = {
+    readonly kind: "preset-tags";
+    readonly moduleId: string;
+    readonly tool: BuiltinTool;
+} | {
+    readonly kind: "always";
+    readonly moduleId: string;
+    readonly tool: ExtensionTool;
+};
+export interface ResolvedEngineHook {
+    readonly moduleId: string;
+    readonly event: HookEventName;
+    readonly handler: CapabilityEngineHookContribution["handler"];
+    readonly priority: number;
+    readonly name: string;
+}
+export interface ResolvedEngineComposition {
+    /**
+     * Effective registry order: every preset-tags tool (module order) first,
+     * then every always tool (module order) — mirrors the current engine's
+     * composeToolCatalog() + registerExtensionModules() sequence.
+     */
+    readonly tools: readonly ResolvedToolContribution[];
+    readonly presets: readonly ResolvedContribution<AgentPreset>[];
+    readonly defaultPreset: string;
+    readonly promptSections: readonly ResolvedContribution<string>[];
+    readonly dynamicContextProviders: readonly ResolvedContribution<CapabilityDynamicContextProvider>[];
+    readonly instructionBoundaries: readonly ResolvedContribution<CapabilityInstructionBoundaryFinder>[];
+    readonly artifactDetectors: readonly ResolvedContribution<CapabilityArtifactDetector>[];
+    readonly fileHistory: readonly ResolvedContribution<CapabilityFileHistoryContribution>[];
+    readonly sessionWorkspaces: readonly ResolvedContribution<SessionWorkspaceCapability>[];
+    readonly hooks: readonly ResolvedEngineHook[];
+    readonly behaviorProfiles: readonly ResolvedContribution<RunBehaviorProfile>[];
+    readonly toolSelectionAdjusters: readonly ResolvedContribution<NonNullable<AgentEngineContributions["adjustToolSelection"]>>[];
+    readonly toolServices: readonly ResolvedContribution<NonNullable<AgentEngineContributions["createToolService"]>>[];
+}
+export interface ResolvedProtocolComposition {
+    readonly queries: readonly ResolvedContribution<ExtensionQueryHandler>[];
+    readonly observerFactories: readonly ResolvedContribution<(host: ProtocolObserverHost) => ProtocolObserver>[];
+    readonly runValidators: readonly ResolvedContribution<(params: Record<string, unknown>) => string | null>[];
+    readonly hiddenSessionKinds: readonly ResolvedContribution<string>[];
+}
+export interface CompositionDiagnostic {
+    readonly code: "empty_module" | "engine_only_module" | "protocol_only_module" | "core_preset_shadowed";
+    readonly moduleId: string;
+    readonly message: string;
+}
+export interface ResolvedComposition {
+    readonly version: 1;
+    readonly digest: string;
+    readonly modules: readonly ResolvedModule[];
+    readonly engine: ResolvedEngineComposition;
+    readonly protocol: ResolvedProtocolComposition;
+    readonly diagnostics: readonly CompositionDiagnostic[];
+}
+export interface CompileCompositionOptions {
+    /** Defaults to CORE_AGENT_MODULE. Overridable only for unit tests. */
+    readonly core?: AgentModule;
+    readonly modules?: readonly AgentModule[];
+    /** Module ids the host requires; missing ids are a compile error. */
+    readonly expectedModules?: readonly string[];
+}
+/** Pure-data projection; never contains functions, prompt bodies or paths. */
+export interface CompositionSnapshot {
+    version: 1;
+    modules: Array<{
+        id: string;
+        order: number;
+        source: string;
+    }>;
+    tools: Array<{
+        name: string;
+        moduleId: string;
+        exposure: "preset-tags" | "always";
+        presetTags: string[];
+    }>;
+    presets: Array<{
+        name: string;
+        moduleId: string;
+        isDefault: boolean;
+    }>;
+    promptSections: Array<{
+        name: string;
+        moduleId: string;
+    }>;
+    hooks: Array<{
+        event: string;
+        name: string;
+        priority: number;
+        moduleId: string;
+    }>;
+    behaviorProfiles: Array<{
+        id: string;
+        moduleId: string;
+    }>;
+    queries: Array<{
+        type: string;
+        moduleId: string;
+    }>;
+    observers: string[];
+    runValidators: string[];
+    hiddenSessionKinds: Array<{
+        kind: string;
+        moduleId: string;
+    }>;
+}

package/dist/composition/types.js

@@ -0,0 +1 @@
+export {};

package/dist/engine/engine.d.ts

@@ -83,7 +83,8 @@ export declare class Engine {
     private runtimeToolRegistry;
     /** Engine-local view containing only this Engine's capability modules. */
     private toolRegistry;
-    private readonly capabilities;
+    /** Compiled module contributions — the single composition fact source. */
+    private readonly composition;
     private readonly toolCatalog;
     private readonly toolGuards;
     /** Per-turn dynamic definition rewriters contributed by builtin exposures. */

package/dist/engine/engine.js

@@ -3,14 +3,12 @@
  */
 import { createLLMClient } from "../llm/client-factory.js";
 import { ToolRegistry } from "../tool-system/registry.js";
-import { queryExtensionModules, registerExtensionModules, } from "../tool-system/capability-module.js";
 import { readLastTodoSnapshot } from "../tool-system/builtin/task.js";
 import { getMergedCatalog } from "../model-catalog/index.js";
 import { modelEntriesFromConnections } from "./model-connections-pool.js";
 import { cumulativeCacheHitRate, foldRunUsage, normalizeCumulativeUsageCounters, } from "../session/usage.js";
 import { enqueueSteerItem, consumeSteerItems, removeSteerItem, } from "./steer-queue.js";
 import { RunEnvironmentResolver } from "./run-environment.js";
-import { BUILTIN_TOOLS, } from "../tool-system/builtin/index.js";
 import { asyncAgentRegistry } from "../tool-system/builtin/agent-registry.js";
 import { skillToolDef } from "../tool-system/builtin/skill.js";
 import { backgroundShellManager } from "../runtime/background-shell.js";
@@ -35,8 +33,10 @@ import { resolveFeatureFlags, } from "../settings/feature-flags.js";
 import { effectiveBuiltinLists, effectiveDisabledList, effectiveProjectOverrides, } from "../capability-control/overlay.js";
 import { computeEffectiveDisabledLists } from "../capability-control/disabled-lists.js";
 import { registerFileHistoryHook } from "./file-history-hook.js";
-import { resolveAgentPreset, resolveBuiltinToolNames } from "../preset/index.js";
-import { composeDynamicContextProviders, composeCapabilityEngineHooks, composePromptSections, composeToolCatalog, resolveCapabilities, resolveInstructionBoundary, } from "../capabilities/index.js";
+import { resolveToolNamesForPreset } from "../preset/index.js";
+import { compileComposition } from "../composition/compiler.js";
+import { ConfigError } from "../exceptions.js";
+import { compositionPromptSections, compositionToolCatalog, presetInjectedTools, registerAlwaysTools, resolveCompositionInstructionBoundary, resolvePresetFromComposition, } from "../composition/resolve-preset.js";
 import { ModelPool } from "../llm/model-pool.js";
 import { AgentDefinitionRegistry } from "../agent/agent-definition-registry.js";
 import { defaultCacheDir } from "../llm/model-cache.js";
@@ -44,7 +44,6 @@ import { detectProviderFromApiKey, buildModelPool } from "../onboarding.js";
 import { detectPastedNoise } from "../utils/task-sanitizer.js";
 import { PromptCacheDiagnosticRecorder, promptCacheDropHint, } from "./prompt-cache-diagnostics.js";
 import { buildRunUserMessageContent, prepareRunImageInput } from "./run-image-input.js";
-import { ISOLATED_TASK_PROFILE, QUICK_CHAT_RESTRICTED_PROFILE, } from "./run-types.js";
 import { createSubAgentSpawner } from "./subagent-spawner.js";
 import { AuxiliaryPipeline, sameLlmIdentity } from "./auxiliary-pipeline.js";
 import { PermissionController } from "./permission-controller.js";
@@ -152,7 +151,8 @@ export class Engine {
     runtimeToolRegistry;
     /** Engine-local view containing only this Engine's capability modules. */
     toolRegistry;
-    capabilities;
+    /** Compiled module contributions — the single composition fact source. */
+    composition;
     toolCatalog;
     toolGuards;
     /** Per-turn dynamic definition rewriters contributed by builtin exposures. */
@@ -400,9 +400,13 @@ export class Engine {
             },
             ...(this.runtime ? { runtime: this.runtime } : {}),
         });
-        this.capabilities = resolveCapabilities(config.capabilities);
-        this.config = { ...config, capabilities: this.capabilities };
-        this.toolCatalog = composeToolCatalog(BUILTIN_TOOLS, this.capabilities, config.extensionModules ?? []);
+        if (config.composition && config.modules) {
+            throw new ConfigError("EngineConfig.composition is mutually exclusive with modules");
+        }
+        // Single composition fact source for every module contribution.
+        this.composition =
+            config.composition ?? compileComposition({ modules: config.modules ?? [] });
+        this.toolCatalog = compositionToolCatalog(this.composition);
         this.toolGuards = new Map(this.toolCatalog.flatMap((tool) => tool.exposure.availability
             ? [[tool.definition.name, tool.exposure.availability]]
             : []));
@@ -410,35 +414,31 @@ export class Engine {
             ? [[tool.definition.name, tool.exposure.rewriteDefinition]]
             : []));
         // Behavior profile registry: core defaults first, then host config, then
-        // extension modules — later registrations override earlier ones by id.
+        // module contributions — later registrations override earlier ones by id.
+        const moduleProfiles = this.composition.engine.behaviorProfiles;
         this.behaviorProfiles = new Map([
-            QUICK_CHAT_RESTRICTED_PROFILE,
-            ISOLATED_TASK_PROFILE,
+            ...moduleProfiles.filter((p) => p.moduleId === "core").map((p) => p.value),
             ...(config.behaviorProfiles ?? []),
-            ...(config.extensionModules ?? []).flatMap((module) => module.behaviorProfiles ?? []),
+            ...moduleProfiles.filter((p) => p.moduleId !== "core").map((p) => p.value),
         ].map((profile) => [profile.id, profile]));
-        this.capabilityPromptSections = composePromptSections(this.capabilities);
-        this.capabilityDynamicContextProviders = composeDynamicContextProviders(this.capabilities);
-        this.preset = resolveAgentPreset(config.preset, this.capabilities);
-        // Extension catalogTools join the active preset regardless of its name:
-        // presets snapshot their tool lists from the catalogs known at module
-        // load, which can never include extension packages. Visibility stays
-        // gated by each tool's exposure.availability guard.
-        const extensionCatalogTools = (config.extensionModules ?? []).flatMap((module) => [
-            ...(module.catalogTools ?? []),
-        ]);
-        if (extensionCatalogTools.length > 0) {
+        this.capabilityPromptSections = compositionPromptSections(this.composition);
+        this.capabilityDynamicContextProviders = this.composition.engine.dynamicContextProviders.map((c) => c.value);
+        this.preset = resolvePresetFromComposition(this.composition, config.preset);
+        // Catalog tools owned by modules that contribute no presets join the
+        // active preset regardless of its name: presets snapshot their tool lists
+        // from catalogs known at module authoring time, which can never include
+        // such packages. Visibility stays gated by exposure.availability.
+        const injectedTools = presetInjectedTools(this.composition);
+        if (injectedTools.length > 0) {
             this.preset = {
                 ...this.preset,
                 builtinTools: [
                     ...this.preset.builtinTools,
-                    ...extensionCatalogTools.map((tool) => tool.definition.name),
+                    ...injectedTools.map((tool) => tool.definition.name),
                 ],
                 defaultPermissionRules: [
                     ...this.preset.defaultPermissionRules,
-                    ...extensionCatalogTools.flatMap((tool) => [
-                        ...(tool.exposure.defaultPermissionRules ?? []),
-                    ]),
+                    ...injectedTools.flatMap((tool) => [...(tool.exposure.defaultPermissionRules ?? [])]),
                 ],
             };
         }
@@ -468,22 +468,22 @@ export class Engine {
         this.runtimeToolRegistry =
             config.runtime?.toolRegistry ??
                 new ToolRegistry({
-                    builtinTools: resolveBuiltinToolNames({
-                        preset: this.preset.name,
+                    builtinTools: resolveToolNamesForPreset({
+                        preset: this.preset,
                         host: config.builtinToolHost,
                         enabledBuiltinTools: [
                             ...builtinLists.enabledBuiltinTools,
-                            // Extension catalogTools are preset-agnostic (see preset merge
+                            // Injected catalog tools are preset-agnostic (see preset merge
                             // above); their availability guards gate actual visibility.
-                            ...extensionCatalogTools.map((tool) => tool.definition.name),
+                            ...injectedTools.map((tool) => tool.definition.name),
                         ],
                         disabledBuiltinTools: builtinLists.disabledBuiltinTools,
-                        capabilities: this.capabilities,
+                        adjusters: this.composition.engine.toolSelectionAdjusters.map((a) => a.value),
                     }),
                     toolCatalog: this.toolCatalog,
                 });
         this.toolRegistry = this.runtimeToolRegistry.fork();
-        registerExtensionModules(this.toolRegistry, config.extensionModules ?? []);
+        registerAlwaysTools(this.composition, this.toolRegistry);
         this.hooks = new HookRegistry();
         // Installed-plugin hooks — declared in each plugin's hooks/hooks.json.
         // Registered first (priority 80) so user-authored hooks at lower
@@ -506,15 +506,13 @@ export class Engine {
         // settings.hooks → shell-command wrappers. Chain order:
         // plugin (80) → shell (50) → capability (20) → SDK code (default 0).
         this.registerSettingsHooks();
-        for (const hook of composeCapabilityEngineHooks(this.capabilities)) {
+        for (const hook of this.composition.engine.hooks) {
             this.hooks.register(hook.event, hook.handler, hook.priority, hook.name);
         }
         for (const hook of config.hooks ?? []) {
             this.hooks.register(hook.event, hook.handler, hook.priority, hook.name);
         }
-        this.sessionManager = new SessionManager(config.sessionStorageDir, this.capabilities
-            .map((capability) => capability.sessionWorkspace)
-            .find((candidate) => candidate !== undefined));
+        this.sessionManager = new SessionManager(config.sessionStorageDir, this.composition.engine.sessionWorkspaces[0]?.value);
         // Initialize model pool — prefer runtime's shared pool, fall back to self-constructed.
         this.modelPool = config.runtime?.modelPool ?? new ModelPool();
         this.auxiliaryPipeline = new AuxiliaryPipeline({
@@ -666,8 +664,11 @@ export class Engine {
         this.toolRegistry.registerTool(definition, executor);
     }
     /** Dispatch a host-installed capability query without teaching core its name. */
-    queryCapability(type, params = {}) {
-        return queryExtensionModules(this.config.extensionModules ?? [], type, params);
+    async queryCapability(type, params = {}) {
+        const handler = this.composition.protocol.queries.find((q) => q.key === type)?.value;
+        if (!handler)
+            return { handled: false };
+        return { handled: true, data: await handler(params) };
     }
     /**
      * Inject the askUser handler after construction. Used by AgentServer
@@ -1756,9 +1757,7 @@ export class Engine {
                 sessionDir: join(this.config.sessionStorageDir ?? sessionsRoot(), session.state.sessionId),
                 cwd,
                 getTurnSeq: () => session.state.turnSeq,
-                contributions: this.capabilities.flatMap((capability) => [
-                    ...(capability.fileHistory ?? []),
-                ]),
+                contributions: this.composition.engine.fileHistory.map((c) => c.value),
             });
         // Hook: agent start
         await this.emitHook("on_agent_start", {
@@ -2004,7 +2003,7 @@ export class Engine {
             sessionBrief: session.state.sessionBrief,
             profileMemoryDir,
             instructionCompatFileNames: compatFileNamesFrom(this.config.instructions),
-            instructionBoundaryFinder: (scanCwd) => resolveInstructionBoundary(scanCwd, this.capabilities),
+            instructionBoundaryFinder: (scanCwd) => resolveCompositionInstructionBoundary(this.composition, scanCwd),
             disabledSkills,
             disabledPlugins,
             skillAllowlist: profileCanUseSkills ? toolCtx.skillAllowlist : [],
@@ -2558,22 +2557,23 @@ export class Engine {
         // (rebuilt per turn from this.preset) reflects the new preset's system
         // prompt / behavior. Only when the preset actually changed.
         if (patch.preset !== undefined && patch.preset !== prevPresetName) {
-            const nextPreset = resolveAgentPreset(this.config.preset, this.capabilities);
+            const nextPreset = resolvePresetFromComposition(this.composition, this.config.preset);
             // The builtin tool SET is ctor-frozen and may be shared via runtime — we
             // do NOT rebuild it here. If the new preset implies a different builtin
             // tool set, that part of the change only lands on session restart.
-            const prevTools = resolveBuiltinToolNames({
-                preset: prevPresetName,
+            const adjusters = this.composition.engine.toolSelectionAdjusters.map((a) => a.value);
+            const prevTools = resolveToolNamesForPreset({
+                preset: resolvePresetFromComposition(this.composition, prevPresetName),
                 host: this.config.builtinToolHost,
-                capabilities: this.capabilities,
+                adjusters,
             })
                 .slice()
                 .sort()
                 .join(",");
-            const nextTools = resolveBuiltinToolNames({
-                preset: nextPreset.name,
+            const nextTools = resolveToolNamesForPreset({
+                preset: nextPreset,
                 host: this.config.builtinToolHost,
-                capabilities: this.capabilities,
+                adjusters,
             })
                 .slice()
                 .sort()
@@ -3278,17 +3278,15 @@ export class Engine {
      */
     buildToolContext(cwd = this.config.cwd ?? process.cwd(), explicitProfileOverrides, profileMemoryDir) {
         const { disabledSkills, disabledPlugins } = this.readDisabledLists(cwd, explicitProfileOverrides);
-        const capabilityServices = Object.fromEntries(this.capabilities.flatMap((capability) => {
-            if (!capability.createToolService)
-                return [];
-            const service = capability.createToolService({
+        const capabilityServices = Object.fromEntries(this.composition.engine.toolServices.map(({ moduleId, value }) => {
+            const service = value({
                 isSubAgent: this.config.isSubAgent === true,
                 settings: this.getSettingsManager(),
                 resolveSandbox: (cwd) => this.runEnvironmentResolver.resolveSandbox(cwd),
                 readShellEnv: (cwd) => this.runEnvironmentResolver.readShellEnv(cwd),
                 getSessionManager: () => this.sessionManager,
             });
-            return [[capability.id, service]];
+            return [moduleId, service];
         }));
         const ctx = {
             shellEnv: this.runEnvironmentResolver.readShellEnv(cwd),

package/dist/engine/subagent-spawner.js

@@ -237,8 +237,8 @@ export function createSubAgentSpawner(deps) {
                 preset: deps.presetName,
                 enabledBuiltinTools: scope.enabled,
                 disabledBuiltinTools: scope.disabled,
-                capabilities: deps.parentConfig.capabilities,
-                extensionModules: deps.parentConfig.extensionModules,
+                composition: deps.parentConfig.composition,
+                modules: deps.parentConfig.modules,
                 builtinToolHost: deps.parentConfig.builtinToolHost,
                 customSystemPrompt: deps.parentConfig.customSystemPrompt,
                 appendSystemPrompt: [deps.parentConfig.appendSystemPrompt, request.appendSystemPrompt]

package/dist/engine/types.d.ts

@@ -21,8 +21,7 @@ import type { SettingsScope } from "../settings/manager.js";
 import type { EngineRuntime } from "./runtime.js";
 import type { HookEventName } from "../hooks/events.js";
 import type { HookHandler } from "../hooks/registry.js";
-import type { CapabilityModule } from "../capabilities/index.js";
-import type { ExtensionModule } from "../tool-system/capability-module.js";
+import type { AgentModule, ResolvedComposition } from "../composition/types.js";
 import type { RunBehaviorProfile } from "./run-types.js";
 import type { LegacyPetWorkDelegation } from "../types.js";
 export interface EngineConfig {
@@ -45,10 +44,14 @@ export interface EngineConfig {
     preset?: AgentPresetName;
     enabledBuiltinTools?: string[];
     disabledBuiltinTools?: string[];
-    /** Trusted optional product capabilities installed by the owning host. */
-    capabilities?: readonly CapabilityModule[];
-    /** Lightweight runtime tools and queries loaded by the host process. */
-    extensionModules?: readonly ExtensionModule[];
+    /**
+     * Precompiled composition from the host root — the single source of truth
+     * for module contributions. Mutually exclusive with modules / capabilities
+     * / extensionModules.
+     */
+    composition?: ResolvedComposition;
+    /** AgentModules for library consumers; Engine compiles them once. */
+    modules?: readonly AgentModule[];
     /**
      * Named per-run behavior profiles selectable via EngineRunOptions.behaviorMode
      * or a profile's activateForSessionKinds. Merged (by id, later wins) over the

package/dist/exceptions.d.ts

@@ -42,6 +42,14 @@ export declare class TranscriptError extends FrameworkError {
 export declare class ConfigError extends FrameworkError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/**
+ * Thrown by compileComposition() on any conflicting or invalid module
+ * contribution. Structured details carry at least { code, key } plus the
+ * owning module ids so hosts can render actionable errors.
+ */
+export declare class CompositionError extends FrameworkError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
 /**
  * Thrown by `resolveSandboxBackend` when an explicit sandbox mode is
  * requested but the corresponding backend is unavailable on this host

package/dist/exceptions.js

@@ -91,6 +91,17 @@ export class ConfigError extends FrameworkError {
         this.name = "ConfigError";
     }
 }
+/**
+ * Thrown by compileComposition() on any conflicting or invalid module
+ * contribution. Structured details carry at least { code, key } plus the
+ * owning module ids so hosts can render actionable errors.
+ */
+export class CompositionError extends FrameworkError {
+    constructor(message, details) {
+        super(message, details);
+        this.name = "CompositionError";
+    }
+}
 // ─── Sandbox Errors ───────────────────────────────────────────────
 /**
  * Thrown by `resolveSandboxBackend` when an explicit sandbox mode is