@cjhyy/code-shell-core 0.8.11 → 0.8.12

package/dist/capabilities/index.d.ts

@@ -1,58 +1,28 @@
 import type { AgentPreset } from "../preset/index.js";
-import type { BuiltinTool } from "../tool-system/builtin/index.js";
 import type { SandboxBackend } from "../tool-system/sandbox/index.js";
 import type { SessionManager } from "../session/session-manager.js";
 import type { ArtifactKind, ArtifactRole } from "../run/types.js";
 import type { HookEventName } from "../hooks/events.js";
 import type { HookHandler } from "../hooks/registry.js";
 /**
- * A host-installable slice of agent behavior.
- *
- * Core owns the lifecycle and execution contracts; product packages contribute
- * tools, presets, and prompt text through this boundary. Modules are plain data
- * so a host can compose them per Engine without mutating process-global state.
+ * Contribution types shared by AgentModule engine contributions
+ * (src/composition/types.ts). The former CapabilityModule interface and its
+ * process-global registry were removed in the composition cutover — product
+ * packages now ship AgentModule factories compiled at the host root.
  */
-export interface CapabilityModule {
-    id: string;
-    tools?: readonly BuiltinTool[];
-    presets?: readonly AgentPreset[];
-    /** Preset selected when this capability is installed and the host did not choose one. */
-    defaultPreset?: string;
-    promptSections?: Readonly<Record<string, string>>;
-    /** Volatile, capability-owned context appended after the cacheable prompt prefix. */
-    dynamicContextProviders?: readonly CapabilityDynamicContextProvider[];
-    /** Optional project boundary for layered instruction discovery. */
-    instructionBoundary?: CapabilityInstructionBoundaryFinder;
-    /** Runtime services exposed only to this capability's tools. */
-    createToolService?(host: CapabilityToolServiceHost): unknown;
-    /** Capability-specific run artifact recognition. */
-    artifactDetectors?: readonly CapabilityArtifactDetector[];
-    /** Pre-mutation snapshot targets for capability-owned compound file tools. */
-    fileHistory?: readonly CapabilityFileHistoryContribution[];
-    /** Optional validation for persisted product-specific workspace pointers. */
-    sessionWorkspace?: SessionWorkspaceCapability;
-    /** Trusted in-process handlers joined to this Engine's normal hook chain. */
-    engineHooks?: readonly CapabilityEngineHookContribution[];
-    adjustToolSelection?(names: Set<string>, context: CapabilityToolSelectionContext): void;
-}
 export interface CapabilityEngineHookContribution {
     event: HookEventName;
     handler: HookHandler;
     priority?: number;
     name?: string;
 }
-export interface ResolvedCapabilityEngineHook extends CapabilityEngineHookContribution {
-    capabilityId: string;
-    priority: number;
-    name: string;
-}
 export interface CapabilityDynamicContext {
     cwd: string;
     preset: AgentPreset;
 }
 export type CapabilityDynamicContextProvider = (context: CapabilityDynamicContext) => string | undefined | Promise<string | undefined>;
 export type CapabilityInstructionBoundaryFinder = (cwd: string) => string | null;
-/** Generic host services from which a capability may build its private tool service. */
+/** Generic host services from which a module may build its private tool service. */
 export interface CapabilityToolServiceHost {
     readonly isSubAgent: boolean;
     readonly settings: {
@@ -88,22 +58,3 @@ export interface CapabilityFileHistoryContribution {
     toolName: string;
     resolveTargets(args: Record<string, unknown>, cwd: string): readonly string[];
 }
-/**
- * Install a capability at a process composition root (CLI/desktop worker).
- * Library consumers should prefer EngineConfig.capabilities for isolation.
- */
-export declare function registerCapability(capability: CapabilityModule): void;
-/** Primarily useful for isolated hosts and tests that own their process. */
-export declare function unregisterCapability(id: string): void;
-export declare function listRegisteredCapabilities(): CapabilityModule[];
-/** Merge process-installed and per-Engine modules, rejecting ambiguous IDs. */
-export declare function resolveCapabilities(local?: readonly CapabilityModule[]): CapabilityModule[];
-export declare function composeToolCatalog(coreTools: readonly BuiltinTool[], capabilities: readonly CapabilityModule[], extensionModules?: readonly {
-    catalogTools?: readonly BuiltinTool[];
-}[]): BuiltinTool[];
-export declare function composePromptSections(capabilities: readonly CapabilityModule[]): Record<string, string>;
-export declare function composeDynamicContextProviders(capabilities: readonly CapabilityModule[]): CapabilityDynamicContextProvider[];
-export declare function composeArtifactDetectors(capabilities: readonly CapabilityModule[]): CapabilityArtifactDetector[];
-/** Normalize code hooks with deterministic names and a product-module priority. */
-export declare function composeCapabilityEngineHooks(capabilities: readonly CapabilityModule[]): ResolvedCapabilityEngineHook[];
-export declare function resolveInstructionBoundary(cwd: string, capabilities: readonly CapabilityModule[]): string | null;

package/dist/capabilities/index.js

@@ -1,80 +1 @@
-const installedCapabilities = new Map();
-/**
- * Install a capability at a process composition root (CLI/desktop worker).
- * Library consumers should prefer EngineConfig.capabilities for isolation.
- */
-export function registerCapability(capability) {
-    const existing = installedCapabilities.get(capability.id);
-    if (existing === capability)
-        return;
-    if (existing)
-        throw new Error(`Capability '${capability.id}' is already registered`);
-    installedCapabilities.set(capability.id, capability);
-}
-/** Primarily useful for isolated hosts and tests that own their process. */
-export function unregisterCapability(id) {
-    installedCapabilities.delete(id);
-}
-export function listRegisteredCapabilities() {
-    return [...installedCapabilities.values()];
-}
-/** Merge process-installed and per-Engine modules, rejecting ambiguous IDs. */
-export function resolveCapabilities(local = []) {
-    const resolved = new Map(installedCapabilities);
-    for (const capability of local) {
-        const existing = resolved.get(capability.id);
-        if (existing && existing !== capability) {
-            throw new Error(`Capability '${capability.id}' was provided more than once`);
-        }
-        resolved.set(capability.id, capability);
-    }
-    return [...resolved.values()];
-}
-export function composeToolCatalog(coreTools, capabilities, extensionModules = []) {
-    const catalog = new Map();
-    for (const tool of [
-        ...coreTools,
-        ...capabilities.flatMap((capability) => [...(capability.tools ?? [])]),
-        ...extensionModules.flatMap((module) => [...(module.catalogTools ?? [])]),
-    ]) {
-        const name = tool.definition.name;
-        if (catalog.has(name))
-            throw new Error(`Tool '${name}' is contributed more than once`);
-        catalog.set(name, tool);
-    }
-    return [...catalog.values()];
-}
-export function composePromptSections(capabilities) {
-    const sections = {};
-    for (const capability of capabilities) {
-        for (const [name, content] of Object.entries(capability.promptSections ?? {})) {
-            if (name in sections)
-                throw new Error(`Prompt section '${name}' is contributed more than once`);
-            sections[name] = content;
-        }
-    }
-    return sections;
-}
-export function composeDynamicContextProviders(capabilities) {
-    return capabilities.flatMap((capability) => [...(capability.dynamicContextProviders ?? [])]);
-}
-export function composeArtifactDetectors(capabilities) {
-    return capabilities.flatMap((capability) => [...(capability.artifactDetectors ?? [])]);
-}
-/** Normalize code hooks with deterministic names and a product-module priority. */
-export function composeCapabilityEngineHooks(capabilities) {
-    return capabilities.flatMap((capability) => (capability.engineHooks ?? []).map((hook, index) => ({
-        ...hook,
-        capabilityId: capability.id,
-        priority: hook.priority ?? 20,
-        name: `capability:${capability.id}:${hook.name ?? `${hook.event}:${index}`}`,
-    })));
-}
-export function resolveInstructionBoundary(cwd, capabilities) {
-    for (const capability of capabilities) {
-        const boundary = capability.instructionBoundary?.(cwd);
-        if (boundary)
-            return boundary;
-    }
-    return null;
-}
+export {};

package/dist/cli/agent-server-stdio.js

@@ -54,31 +54,29 @@ import { cronScheduler } from "../automation/scheduler.js";
 import { CronStore, defaultCronStorePath } from "../automation/store.js";
 import { resolveLLMConfigForTag } from "../engine/resolve-llm-config.js";
 import { createIpcCredentialAccess, setDefaultCredentialAccess } from "../credentials/access.js";
-async function loadConfiguredExtensionModules() {
+import { compileComposition } from "../composition/compiler.js";
+/**
+ * Load AgentModules from CODE_SHELL_CAPABILITY_MODULES: comma-separated
+ * "specifier#exportName" entries (exportName defaults to createModule).
+ * Fail loud — a silently skipped module used to surface much later as an
+ * unexplained missing tool or "unknown behavior profile: pet".
+ */
+async function loadConfiguredAgentModules() {
     const specs = (process.env.CODE_SHELL_CAPABILITY_MODULES ?? "")
         .split(",")
         .map((entry) => entry.trim())
         .filter(Boolean);
     const modules = [];
     for (const spec of specs) {
-        const [moduleId, exportName = "createCapability"] = spec.split("#", 2);
+        const [moduleId, exportName = "createModule"] = spec.split("#", 2);
         if (!moduleId)
             continue;
-        try {
-            const loaded = (await import(moduleId));
-            const factory = loaded[exportName];
-            if (typeof factory !== "function") {
-                throw new Error(`export ${exportName} is not a capability factory`);
-            }
-            modules.push(factory());
-        }
-        catch (err) {
-            logger.warn("capability.module_unavailable", {
-                moduleId,
-                exportName,
-                error: err instanceof Error ? err.message : String(err),
-            });
+        const loaded = (await import(moduleId));
+        const factory = loaded[exportName];
+        if (typeof factory !== "function") {
+            throw new Error(`CODE_SHELL_CAPABILITY_MODULES: export ${exportName} of ${moduleId} is not an AgentModule factory`);
         }
+        modules.push(factory());
     }
     return modules;
 }
@@ -112,7 +110,9 @@ export function resolveSessionCwd(slice) {
 }
 // ─── Read base config from environment / settings ─────────────────
 const cwd = process.env.AGENT_CWD ?? process.cwd();
-const extensionModules = await loadConfiguredExtensionModules();
+// Compile ONCE at the host root; seed engine, per-session engines and the
+// AgentServer all consume this same composition (design §9.3).
+const composition = compileComposition({ modules: await loadConfiguredAgentModules() });
 // Injectable data root (identity dimension foundations, Task 3). Server
 // Phase 2 per-user workers spawn this entry with CODE_SHELL_DATA_ROOT set to
 // the user's isolated data root; session persistence (engine session store,
@@ -159,7 +159,7 @@ const seedEngine = new Engine({
     enabledBuiltinTools: settings.agent.enabledBuiltinTools,
     disabledBuiltinTools: settings.agent.disabledBuiltinTools,
     builtinToolHost: "desktop",
-    extensionModules,
+    composition,
     settingsScope: "full",
     // No runtime — Engine.populateModelPoolFromSettings() runs in ctor.
 });
@@ -265,7 +265,7 @@ const chatManager = new ChatSessionManager({
             // session it creates is a desktop-origin session.
             origin: "desktop",
             builtinToolHost: "desktop",
-            extensionModules,
+            composition,
             // Inherit full scope so spawned subagents read user config too.
             settingsScope: "full",
             // MCP servers from settings — the worker reads the full disk
@@ -350,11 +350,11 @@ setCapabilityChangedSink(() => {
 // ChatSession (that only happens on a send), so chatManager.get() misses. This
 // reads the same ~/.code-shell/sessions/<id>/state.json every Engine writes, so
 // the goal block re-surfaces on load ("goal 还在但页面不显示" fix).
-const goalDiskReader = new SessionManager(dataSessionsDir);
+const goalDiskReader = new SessionManager(dataSessionsDir, composition.engine.sessionWorkspaces[0]?.value);
 const agentServer = new AgentServer({
     chatManager,
     transport: stdioTransport,
-    extensionModules,
+    composition,
     workspaceBridge: true,
     panelBridge: true,
     // Cold background-wakeup rehydrate must read the same sessions store the

package/dist/composition/compiler.d.ts

@@ -0,0 +1,7 @@
+import type { CompileCompositionOptions, ResolvedComposition } from "./types.js";
+/**
+ * Pure composition compiler (design §7): same input produces the same
+ * frozen ResolvedComposition, identical order and digest. Conflicts fail
+ * loud with both owning module ids; no I/O, no resource creation.
+ */
+export declare function compileComposition(options?: CompileCompositionOptions): ResolvedComposition;

package/dist/composition/compiler.js

@@ -0,0 +1,247 @@
+import { CompositionError } from "../exceptions.js";
+import { DEFAULT_AGENT_PRESET } from "../preset/index.js";
+import { CORE_AGENT_MODULE } from "./core-module.js";
+import { computeCompositionDigest, toCompositionSnapshot } from "./snapshot.js";
+const MODULE_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+function registerModules(options) {
+    const core = options.core ?? CORE_AGENT_MODULE;
+    const registered = [];
+    const seen = new Set();
+    const push = (module, source) => {
+        if (!MODULE_ID_PATTERN.test(module.id)) {
+            throw new CompositionError(`Invalid module id: "${module.id}"`, {
+                code: "invalid_module_id",
+                key: module.id,
+            });
+        }
+        if (seen.has(module.id)) {
+            throw new CompositionError(`Duplicate module id: "${module.id}"`, {
+                code: "duplicate_module",
+                key: module.id,
+            });
+        }
+        seen.add(module.id);
+        registered.push({
+            module,
+            resolved: { id: module.id, order: registered.length, source },
+        });
+    };
+    push(core, "core");
+    for (const module of options.modules ?? [])
+        push(module, "host");
+    for (const id of options.expectedModules ?? []) {
+        if (!seen.has(id)) {
+            throw new CompositionError(`Expected module "${id}" is missing`, {
+                code: "missing_expected_module",
+                key: id,
+            });
+        }
+    }
+    return registered;
+}
+function moduleDiagnostics(registered) {
+    const diagnostics = [];
+    for (const { module, resolved } of registered) {
+        if (resolved.source === "core")
+            continue;
+        const hasEngine = module.engine !== undefined;
+        const hasProtocol = module.protocol !== undefined;
+        if (!hasEngine && !hasProtocol) {
+            diagnostics.push({
+                code: "empty_module",
+                moduleId: module.id,
+                message: `Module "${module.id}" declares no contributions`,
+            });
+        }
+        else if (!hasProtocol) {
+            diagnostics.push({
+                code: "engine_only_module",
+                moduleId: module.id,
+                message: `Module "${module.id}" contributes engine surface only`,
+            });
+        }
+        else if (!hasEngine) {
+            diagnostics.push({
+                code: "protocol_only_module",
+                moduleId: module.id,
+                message: `Module "${module.id}" contributes protocol surface only`,
+            });
+        }
+    }
+    return diagnostics;
+}
+function duplicate(kind, key, firstModuleId, secondModuleId) {
+    return new CompositionError(`Duplicate ${kind} "${key}" contributed by "${firstModuleId}" and "${secondModuleId}"`, { code: `duplicate_${kind.replaceAll(" ", "_")}`, key, firstModuleId, secondModuleId });
+}
+/** Collect keyed contributions across modules, failing loud on duplicates. */
+function collectKeyed(registered, kind, pick) {
+    const owners = new Map();
+    const collected = [];
+    for (const { module } of registered) {
+        for (const [key, value] of pick(module)) {
+            const owner = owners.get(key);
+            if (owner !== undefined)
+                throw duplicate(kind, key, owner, module.id);
+            owners.set(key, module.id);
+            collected.push({ key, moduleId: module.id, value });
+        }
+    }
+    return collected;
+}
+/** One optional contribution per module (e.g. instructionBoundary). */
+function collectSingle(registered, pick) {
+    return registered.flatMap(({ module }) => {
+        const value = pick(module);
+        return value === undefined ? [] : [{ key: module.id, moduleId: module.id, value }];
+    });
+}
+/** Ordered, non-keyed contributions (providers, detectors, file-history). */
+function collectMany(registered, pick) {
+    return registered.flatMap(({ module }) => (pick(module) ?? []).map((value, index) => ({
+        key: `${module.id}:${index}`,
+        moduleId: module.id,
+        value,
+    })));
+}
+function collectEngine(registered, diagnostics) {
+    // Tools: preset-tags join the composed catalog (module order), always tools
+    // are appended afterwards — mirroring composeToolCatalog() followed by
+    // registerExtensionModules() in the current engine constructor.
+    const toolOwners = new Map();
+    const presetTagTools = [];
+    const alwaysTools = [];
+    for (const { module } of registered) {
+        for (const contribution of module.engine?.tools ?? []) {
+            const name = contribution.tool.definition.name;
+            const owner = toolOwners.get(name);
+            if (owner !== undefined)
+                throw duplicate("tool", name, owner, module.id);
+            toolOwners.set(name, module.id);
+            if (contribution.kind === "preset-tags") {
+                presetTagTools.push({ kind: "preset-tags", moduleId: module.id, tool: contribution.tool });
+            }
+            else {
+                alwaysTools.push({ kind: "always", moduleId: module.id, tool: contribution.tool });
+            }
+        }
+    }
+    const tools = [...presetTagTools, ...alwaysTools];
+    // Presets: a host module may shadow a CORE preset of the same name — this
+    // mirrors resolveAgentPreset(), which resolves capability-contributed
+    // presets before builtins (e.g. coding's extended "general"). The shadow is
+    // surfaced as a diagnostic; host-vs-host duplicates still fail loud.
+    const presets = [];
+    const presetIndex = new Map();
+    const coreModuleId = registered[0]?.resolved.id ?? "core";
+    for (const { module } of registered) {
+        for (const preset of module.engine?.presets ?? []) {
+            const existing = presetIndex.get(preset.name);
+            if (existing === undefined) {
+                presetIndex.set(preset.name, presets.length);
+                presets.push({ key: preset.name, moduleId: module.id, value: preset });
+                continue;
+            }
+            const owner = presets[existing];
+            if (!owner || owner.moduleId !== coreModuleId) {
+                throw duplicate("preset", preset.name, owner?.moduleId ?? coreModuleId, module.id);
+            }
+            presets[existing] = { key: preset.name, moduleId: module.id, value: preset };
+            diagnostics.push({
+                code: "core_preset_shadowed",
+                moduleId: module.id,
+                message: `Module "${module.id}" shadows core preset "${preset.name}"`,
+            });
+        }
+    }
+    // Default preset: at most one distinct declaration wins; none → core default.
+    let defaultPreset;
+    for (const { module } of registered) {
+        const declared = module.engine?.defaultPreset;
+        if (!declared)
+            continue;
+        if (defaultPreset && defaultPreset.name !== declared) {
+            throw new CompositionError(`Conflicting default presets: "${defaultPreset.name}" (${defaultPreset.moduleId}) vs "${declared}" (${module.id})`, {
+                code: "conflicting_default_preset",
+                key: declared,
+                firstModuleId: defaultPreset.moduleId,
+                secondModuleId: module.id,
+            });
+        }
+        defaultPreset ??= { name: declared, moduleId: module.id };
+    }
+    const defaultPresetName = defaultPreset?.name ?? DEFAULT_AGENT_PRESET;
+    if (!presets.some((p) => p.key === defaultPresetName)) {
+        throw new CompositionError(`Default preset "${defaultPresetName}" is not contributed`, {
+            code: "unknown_default_preset",
+            key: defaultPresetName,
+            firstModuleId: defaultPreset?.moduleId ?? "core",
+        });
+    }
+    // Preset tool references must resolve to preset-tags tools.
+    const presetTagToolNames = new Set(presetTagTools.map((t) => t.tool.definition.name));
+    for (const { key, moduleId, value } of presets) {
+        for (const toolName of value.builtinTools) {
+            if (!presetTagToolNames.has(toolName)) {
+                throw new CompositionError(`Preset "${key}" references unknown tool "${toolName}"`, {
+                    code: "unknown_preset_tool",
+                    key: toolName,
+                    firstModuleId: moduleId,
+                });
+            }
+        }
+    }
+    const promptSections = collectKeyed(registered, "prompt section", (m) => Object.entries(m.engine?.promptSections ?? {}));
+    const behaviorProfiles = collectKeyed(registered, "behavior profile", (m) => (m.engine?.behaviorProfiles ?? []).map((p) => [p.id, p]));
+    const hooks = registered.flatMap(({ module }) => (module.engine?.hooks ?? []).map((hook, index) => ({
+        moduleId: module.id,
+        event: hook.event,
+        handler: hook.handler,
+        priority: hook.priority ?? 20,
+        name: `capability:${module.id}:${hook.name ?? `${hook.event}:${index}`}`,
+    })));
+    return {
+        tools,
+        presets,
+        defaultPreset: defaultPresetName,
+        promptSections,
+        dynamicContextProviders: collectMany(registered, (m) => m.engine?.dynamicContextProviders),
+        instructionBoundaries: collectSingle(registered, (m) => m.engine?.instructionBoundary),
+        artifactDetectors: collectMany(registered, (m) => m.engine?.artifactDetectors),
+        fileHistory: collectMany(registered, (m) => m.engine?.fileHistory),
+        sessionWorkspaces: collectSingle(registered, (m) => m.engine?.sessionWorkspace),
+        hooks,
+        behaviorProfiles,
+        toolSelectionAdjusters: collectSingle(registered, (m) => m.engine?.adjustToolSelection),
+        toolServices: collectSingle(registered, (m) => m.engine?.createToolService),
+    };
+}
+function collectProtocol(registered) {
+    const queries = collectKeyed(registered, "query", (m) => Object.entries(m.protocol?.queries ?? {}));
+    const hiddenSessionKinds = collectKeyed(registered, "hidden session kind", (m) => (m.protocol?.hiddenSessionKinds ?? []).map((k) => [k, k]));
+    return {
+        queries,
+        observerFactories: collectSingle(registered, (m) => m.protocol?.createObserver),
+        runValidators: collectSingle(registered, (m) => m.protocol?.validateRunParams),
+        hiddenSessionKinds,
+    };
+}
+/**
+ * Pure composition compiler (design §7): same input produces the same
+ * frozen ResolvedComposition, identical order and digest. Conflicts fail
+ * loud with both owning module ids; no I/O, no resource creation.
+ */
+export function compileComposition(options = {}) {
+    const registered = registerModules(options);
+    const diagnostics = moduleDiagnostics(registered);
+    const engine = collectEngine(registered, diagnostics);
+    const protocol = collectProtocol(registered);
+    const draft = {
+        version: 1,
+        modules: Object.freeze(registered.map((r) => r.resolved)),
+        engine,
+        protocol,
+        diagnostics: Object.freeze(diagnostics),
+    };
+    const digest = computeCompositionDigest(toCompositionSnapshot(draft));
+    return Object.freeze({ ...draft, digest });
+}

package/dist/composition/core-module.d.ts

@@ -0,0 +1,10 @@
+import type { AgentModule } from "./types.js";
+/**
+ * Core's own declarations expressed as a module so one compiler handles a
+ * single data path. This does NOT make core unloadable or overridable —
+ * it is always module order 0 and duplicate keys against it fail loud.
+ *
+ * No defaultPreset here: the compiler falls back to DEFAULT_AGENT_PRESET
+ * only when no product module declares one (mirrors resolveAgentPreset).
+ */
+export declare const CORE_AGENT_MODULE: AgentModule;

package/dist/composition/core-module.js

@@ -0,0 +1,19 @@
+import { BUILTIN_TOOLS } from "../tool-system/builtin/index.js";
+import { BUILTIN_AGENT_PRESETS } from "../preset/index.js";
+import { ISOLATED_TASK_PROFILE, QUICK_CHAT_RESTRICTED_PROFILE } from "../engine/run-types.js";
+/**
+ * Core's own declarations expressed as a module so one compiler handles a
+ * single data path. This does NOT make core unloadable or overridable —
+ * it is always module order 0 and duplicate keys against it fail loud.
+ *
+ * No defaultPreset here: the compiler falls back to DEFAULT_AGENT_PRESET
+ * only when no product module declares one (mirrors resolveAgentPreset).
+ */
+export const CORE_AGENT_MODULE = {
+    id: "core",
+    engine: {
+        tools: BUILTIN_TOOLS.map((tool) => ({ kind: "preset-tags", tool })),
+        presets: Object.values(BUILTIN_AGENT_PRESETS),
+        behaviorProfiles: [QUICK_CHAT_RESTRICTED_PROFILE, ISOLATED_TASK_PROFILE],
+    },
+};

package/dist/composition/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { CORE_AGENT_MODULE } from "./core-module.js";
+export { compileComposition } from "./compiler.js";
+export { toCompositionSnapshot, computeCompositionDigest } from "./snapshot.js";
+export { compositionPromptSections, compositionToolCatalog, presetInjectedTools, registerAlwaysTools, resolveCompositionInstructionBoundary, resolvePresetFromComposition, } from "./resolve-preset.js";

package/dist/composition/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export { CORE_AGENT_MODULE } from "./core-module.js";
+export { compileComposition } from "./compiler.js";
+export { toCompositionSnapshot, computeCompositionDigest } from "./snapshot.js";
+export { compositionPromptSections, compositionToolCatalog, presetInjectedTools, registerAlwaysTools, resolveCompositionInstructionBoundary, resolvePresetFromComposition, } from "./resolve-preset.js";

package/dist/composition/protocol-attach.d.ts

@@ -0,0 +1,15 @@
+import type { ExtensionQueryHandler, ProtocolObserver, ProtocolObserverHost } from "../tool-system/capability-module.js";
+import type { ResolvedComposition } from "./types.js";
+/**
+ * Wire a resolved protocol composition into an AgentServer's observer list
+ * and query dispatch table. Observer factories run first (isolated per
+ * module — a throwing factory only loses its own observer); declared
+ * queries never clobber a handler an observer registered at create time.
+ */
+export declare function attachProtocolContributions(opts: {
+    protocol: ResolvedComposition["protocol"];
+    host: ProtocolObserverHost;
+    observers: ProtocolObserver[];
+    queryHandlers: Map<string, ExtensionQueryHandler>;
+    warn: (message: string) => void;
+}): void;

package/dist/composition/protocol-attach.js

@@ -0,0 +1,21 @@
+/**
+ * Wire a resolved protocol composition into an AgentServer's observer list
+ * and query dispatch table. Observer factories run first (isolated per
+ * module — a throwing factory only loses its own observer); declared
+ * queries never clobber a handler an observer registered at create time.
+ */
+export function attachProtocolContributions(opts) {
+    for (const factory of opts.protocol.observerFactories) {
+        try {
+            opts.observers.push(factory.value(opts.host));
+        }
+        catch (err) {
+            opts.warn(`protocol observer init failed for module ${factory.moduleId}: ${err.message}`);
+        }
+    }
+    for (const query of opts.protocol.queries) {
+        if (!opts.queryHandlers.has(query.key)) {
+            opts.queryHandlers.set(query.key, query.value);
+        }
+    }
+}

package/dist/composition/resolve-preset.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Runtime helpers over a ResolvedComposition. Preset selection and
+ * validation happen HERE, at use time — not at compile time — because the
+ * preset can change per session (config slice) and per settings hot reload.
+ */
+import type { AgentPreset } from "../preset/index.js";
+import type { BuiltinTool } from "../tool-system/builtin/index.js";
+import type { ExtensionTool } from "../tool-system/capability-module.js";
+import type { ResolvedComposition } from "./types.js";
+/** Resolve a preset by name (or the composition default), failing loud. */
+export declare function resolvePresetFromComposition(composition: ResolvedComposition, name?: string): AgentPreset;
+/** All preset-tags tools — the composed catalog in effective order. */
+export declare function compositionToolCatalog(composition: ResolvedComposition): BuiltinTool[];
+/**
+ * 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 declare function presetInjectedTools(composition: ResolvedComposition): BuiltinTool[];
+/** Module-contributed named prompt sections as a plain record. */
+export declare function compositionPromptSections(composition: ResolvedComposition): Record<string, string>;
+/**
+ * Register always-exposure tools on the engine-local registry fork.
+ * Cross-module uniqueness is compiler-enforced; this guards collisions with
+ * runtime-registered tools.
+ */
+export declare function registerAlwaysTools(composition: ResolvedComposition, registry: {
+    hasTool(name: string): boolean;
+    registerTool(definition: ExtensionTool["definition"], execute: ExtensionTool["execute"]): void;
+}): void;
+/** First non-null module instruction boundary, in module order. */
+export declare function resolveCompositionInstructionBoundary(composition: ResolvedComposition, cwd: string): string | null;