@capekai/core 1.0.0

package/src/plugins/compose.ts

@@ -0,0 +1,171 @@
+/**
+ * C2 composition helpers. Scope creation is async (kernel activation);
+ * entering a composed agent scope is fully synchronous: every service is
+ * resolved and every AsyncLocalStorage accessor is seeded before the
+ * callback starts, so no async work runs with unseeded accessors.
+ */
+
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { withRuntimeConfiguration } from '../configuration/runtime';
+import { withContextAssembler } from '../context/assembler';
+import { withContextSources } from '../context/sources';
+import { withRetryPolicy } from '../retry/policy';
+import { withCompactionService } from '../compaction/policy';
+import { withAskPermissionPolicy } from '../permission/policy';
+import { withPermissionRuntimeService } from '../permission/runtime';
+import { withWorkspaceService } from '../workspace/policy';
+import { withToolOutputService } from '../tool-output/policy';
+import { withGoalDomain } from '../goals/service';
+import { createAgentScope } from '../kernel/kernel';
+export { createAgentScope, createProcessScope } from '../kernel/kernel';
+import type { AgentScopeHandle, ProcessScopeHandle } from '../kernel/types';
+import { withProviderOverrides } from '../providers/registry';
+import {
+  DOMAIN_TOOL_PAYLOAD_FIELD,
+  isDomainToolPayload,
+  withContributedDomainToolPayloads,
+  type DomainToolPayload,
+} from '../runtime/domain-tool-source';
+import { withRuntimeHost, getRuntimeHost, type RuntimeHost } from '../runtime/host';
+import { createStandaloneHost } from '../runtime/standalone-host';
+import { withSandboxController } from '../sandbox/controller';
+import { withStorage } from '../storage/runtime';
+import { withToolRegistryResolver } from '../tools/registry';
+import { withWorkspaceToolDiscovery } from '../tools/tool-source';
+import { createFacadeAgentPlugins, type FacadeScopeValues } from './facade-plugins';
+export { facadeProcessPlugins } from './facade-plugins';
+import { capekGoalDomainKey } from './goal-domain';
+import {
+  capekContextAssemblerKey,
+  capekContextSourcesKey,
+  capekProviderOverridesKey,
+  capekRuntimeConfigurationKey,
+  capekRuntimeHostKey,
+  capekRetryPolicyKey,
+  capekCompactionServiceKey,
+  capekPermissionPolicyKey,
+  capekPermissionRuntimeKey,
+  capekWorkspacePolicyKey,
+  capekToolOutputPolicyKey,
+  capekSandboxControllerKey,
+  capekStorageKey,
+  capekToolResolverKey,
+  capekWorkspaceToolDiscoveryKey,
+} from './service-keys';
+
+export interface Composition {
+  readonly processScope: ProcessScopeHandle;
+  readonly agentScope: AgentScopeHandle;
+}
+
+/** Composes one agent scope above an explicit process scope using the
+ * package's curated plugin set. The C6 policy providers read the ambient
+ * runtime host (tool-output temp root) at activation, so composition runs
+ * inside `withRuntimeHost`; when no host is configured ambiently, the
+ * reference standalone host is installed for the composition's duration.
+ * The caller owns both scopes' lifetimes:
+ * `await composition.agentScope.dispose()` and
+ * `await composition.processScope.dispose()` when done. Multiple agent
+ * scopes may share one process scope concurrently. */
+export async function createComposition(
+  processScope: ProcessScopeHandle,
+  values: FacadeScopeValues,
+): Promise<Composition> {
+  let ambient: RuntimeHost | undefined;
+  try {
+    ambient = getRuntimeHost();
+  } catch {
+    // No ambient host configured; the reference standalone host covers
+    // composition-time activation reads (tool-output temp root).
+    ambient = undefined;
+  }
+  return withRuntimeHost(ambient ?? createStandaloneHost({
+    workspace: process.cwd(),
+    sandboxActive: false,
+    tempRoot: join(tmpdir(), 'capek-composition'),
+  }), () =>
+    createAgentScope(
+      processScope,
+      [...createFacadeAgentPlugins(values)],
+    ).then((agentScope): Composition => ({ processScope, agentScope })));
+}
+
+/**
+ * Synchronously seeds every current accessor from the composed agent scope
+ * and then runs the callback. Seeding order is fixed: storage, runtime
+ * configuration, runtime host, context sources, provider overrides, optional
+ * tool resolver, tool source, sandbox controller, context assembler. The
+ * optional resolver layer is omitted when no plugin contributed it,
+ * exactly like the unseeded installed-tool path today. The scope's
+ * assembler is bound to this scope at composition time and seeded here
+ * through the context-assembler ALS runtime, so ordered context assembly
+ * always resolves this exact scope, even across async suspensions and
+ * interleaved scopes.
+ *
+ * Contributed domain tool payloads are seeded generically from the scope's
+ * visible tool contributions carrying `DOMAIN_TOOL_PAYLOAD_FIELD`; an empty
+ * map means a composed scope without domain payloads, which disables the
+ * unscoped legacy fallbacks for the callback duration.
+ */
+export function enterAgentScope<T>(scope: AgentScopeHandle, callback: () => T): T {
+  const storage = scope.require(capekStorageKey);
+  const configuration = scope.require(capekRuntimeConfigurationKey);
+  const host = scope.require(capekRuntimeHostKey);
+  const retryPolicy = scope.require(capekRetryPolicyKey);
+  const compactionService = scope.require(capekCompactionServiceKey);
+  const permissionPolicy = scope.require(capekPermissionPolicyKey);
+  const permissionRuntime = scope.require(capekPermissionRuntimeKey);
+  const workspacePolicy = scope.require(capekWorkspacePolicyKey);
+  const toolOutputPolicy = scope.require(capekToolOutputPolicyKey);
+  const contextSources = scope.require(capekContextSourcesKey);
+  const providerOverrides = scope.require(capekProviderOverridesKey);
+  const workspaceToolDiscovery = scope.require(capekWorkspaceToolDiscoveryKey);
+  const sandboxController = scope.require(capekSandboxControllerKey);
+  const toolResolver = scope.optional(capekToolResolverKey);
+  const contextAssembler = scope.require(capekContextAssemblerKey);
+  const goalDomain = scope.optional(capekGoalDomainKey);
+
+  const domainToolPayloads = new Map<string, DomainToolPayload>();
+  for (const tool of scope.listTools()) {
+    if (!tool.visible) continue;
+    const candidate = tool.definition[DOMAIN_TOOL_PAYLOAD_FIELD];
+    if (isDomainToolPayload(candidate) && candidate.name === tool.definition.name) {
+      domainToolPayloads.set(candidate.name, candidate);
+    }
+  }
+
+  const resolveTools = toolResolver === undefined
+    ? (inner: () => T): T => withWorkspaceToolDiscovery(workspaceToolDiscovery, () =>
+      withSandboxController(sandboxController, inner))
+    : (inner: () => T): T => withToolRegistryResolver(toolResolver, () =>
+      withWorkspaceToolDiscovery(workspaceToolDiscovery, () =>
+        withSandboxController(sandboxController, inner)));
+
+  const resolveGoalDomain = goalDomain === undefined
+    ? (inner: () => T): T => inner()
+    : (inner: () => T): T => withGoalDomain(goalDomain, inner);
+
+  return withContributedDomainToolPayloads(domainToolPayloads, () =>
+    resolveGoalDomain(() =>
+      withContextAssembler(contextAssembler, () =>
+        withRetryPolicy(retryPolicy, () =>
+          withCompactionService(compactionService, () =>
+            withAskPermissionPolicy(permissionPolicy, () =>
+              withPermissionRuntimeService(permissionRuntime, () =>
+                withWorkspaceService(workspacePolicy, () =>
+                  withToolOutputService(toolOutputPolicy, () =>
+                    withStorage(storage, () =>
+                      withRuntimeConfiguration(configuration, () =>
+                        withRuntimeHost(host, () =>
+                          withContextSources(contextSources, () =>
+                            withProviderOverrides(providerOverrides, () =>
+                              resolveTools(callback)))))))))))))));
+}
+
+export type {
+  AgentScopeHandle,
+  CapekPlugin,
+  ProcessScopeHandle,
+  ToolDefinition,
+} from '../kernel/types';

package/src/plugins/context-sections.ts

@@ -0,0 +1,246 @@
+import {
+  validateContextAssemblyData,
+  type ContextAssembler,
+  type ContextAssemblyData,
+} from '../context/assembler';
+import {
+  formatInstructions,
+  getAgentDirectory,
+  loadInstructions,
+  readAgentMemoryFile,
+} from '../context/sources';
+import { buildWorkspaceSystemPrompt } from '../context/workspace';
+import type {
+  CapekPlugin,
+  ContextBuildContext,
+  ContextSectionContribution,
+  PluginContext,
+  ProvidedContextSection,
+} from '../kernel/types';
+import { loadMemoryInstructions } from '../memory';
+import { getHostGuidance } from '../runtime/host-guidance';
+import { getHostLayout } from '../runtime/host-layout';
+import { getWorkspace } from '../storage/runtime';
+import {
+  legacySelfDelegationGuidanceSection,
+  legacySessionSearchGuidanceSection,
+} from './legacy-system-message';
+import { capekContextAssemblerKey } from './service-keys';
+
+/**
+ * C3 ordered context contributions.
+ *
+ * Registers the exact current system-message sections, wrappers, omission
+ * rules, and order as kernel context contributions. Byte parity with the
+ * fixed builder is preserved because the guidance constants and section
+ * formats are shared with `legacy-system-message`, and the assembler joins
+ * provided sections with '\n\n' exactly like the fixed builder's append
+ * chain, including the empty-prompt artifact (the system-prompt section
+ * always provides a string, even when it is empty).
+ *
+ * The ordered assembler is bound to its owning scope at composition time
+ * through the narrow `PluginContext.buildContext` closure: it never resolves
+ * an ambient active scope at build time. Two simultaneous agents never share
+ * an assembler view, and a captured assembler keeps building exactly its own
+ * scope's sections even while another scope is entered.
+ */
+
+type SectionContribution = ContextSectionContribution<ContextAssemblyData>;
+
+/** Every contribution receives assembly options through the typed narrow
+ * data path and validates them, so malformed data fails predictably instead
+ * of surfacing unsafe property access. */
+function requiredData(context: ContextBuildContext<ContextAssemblyData>): ContextAssemblyData {
+  return validateContextAssemblyData(context.data);
+}
+
+export const CURRENT_CONTEXT_SECTION_IDS = [
+  'agent-memory',
+  'agent-user-preferences',
+  'system-prompt',
+  'memory-skills-guidance',
+  'self-delegation',
+  'instructions',
+  'workspace',
+  'workspace-memory',
+  'memory-guidance',
+  'skill-management-guidance',
+  'session-search-guidance',
+] as const;
+
+const CONTEXT_SECTIONS: readonly SectionContribution[] = [
+  {
+    id: 'system-prompt',
+    phase: 'identity',
+    order: 30,
+    provide: (context) => {
+      const data = requiredData(context);
+      // Never null: an empty prompt is a real artifact of the fixed builder,
+      // and the '\n\n' join must reproduce its exact bytes.
+      return data.preconfig.systemPrompt || '';
+    },
+  },
+  {
+    id: 'instructions',
+    phase: 'instructions',
+    order: 10,
+    provide: async (context) => {
+      const data = requiredData(context);
+      const instructions = await loadInstructions(data.workspacePath);
+      return formatInstructions(instructions);
+    },
+  },
+  {
+    id: 'workspace',
+    phase: 'workspace',
+    order: 10,
+    provide: (context) => {
+      const data = requiredData(context);
+      return data.workspacePath
+        ? buildWorkspaceSystemPrompt(data.workspacePath, data.additionalPaths)
+        : null;
+    },
+  },
+];
+
+/** The legacy memory and skills contributions, kept for facade and legacy
+ * compositions that reproduce the fixed builder byte-for-byte. The C5
+ * memory and skills domain plugins own these sections in the current Jean2
+ * composition; `createContextSectionsPlugin` includes them only when its
+ * `includeMemorySkillsSections` option stays at the legacy default. */
+const LEGACY_MEMORY_SKILLS_SECTIONS: readonly SectionContribution[] = [
+  {
+    id: 'agent-memory',
+    phase: 'identity',
+    order: 10,
+    provide: async (context) => {
+      const data = requiredData(context);
+      const agentDir = await getAgentDirectory(data.preconfig.id);
+      if (!agentDir) return null;
+      const memory = await readAgentMemoryFile(data.preconfig.id, 'MEMORY.md');
+      return memory ? `<agent_memory>\n${memory}\n</agent_memory>` : null;
+    },
+  },
+  {
+    id: 'agent-user-preferences',
+    phase: 'identity',
+    order: 20,
+    provide: async (context) => {
+      const data = requiredData(context);
+      const agentDir = await getAgentDirectory(data.preconfig.id);
+      if (!agentDir) return null;
+      const memory = await readAgentMemoryFile(data.preconfig.id, 'USER.md');
+      return memory ? `<agent_user_preferences>\n${memory}\n</agent_user_preferences>` : null;
+    },
+  },
+  {
+    id: 'memory-skills-guidance',
+    phase: 'identity',
+    order: 40,
+    provide: async (context) => {
+      const data = requiredData(context);
+      const agentDir = await getAgentDirectory(data.preconfig.id);
+      return agentDir ? getHostGuidance().agentMemorySkills : null;
+    },
+  },
+  {
+    id: 'workspace-memory',
+    phase: 'workspace',
+    order: 20,
+    provide: async (context) => {
+      const data = requiredData(context);
+      if (!data.workspaceId) return null;
+      const workspace = await getWorkspace(data.workspaceId);
+      if (!workspace?.settings?.memory?.enabled || !data.workspacePath) return null;
+      return loadMemoryInstructions(getHostLayout().workspaceMemoryDir(data.workspacePath));
+    },
+  },
+  {
+    id: 'memory-guidance',
+    phase: 'workspace',
+    order: 30,
+    provide: async (context) => {
+      const data = requiredData(context);
+      if (!data.workspaceId) return null;
+      const workspace = await getWorkspace(data.workspaceId);
+      return workspace?.settings?.memory?.enabled && data.workspacePath ? getHostGuidance().memory : null;
+    },
+  },
+  {
+    id: 'skill-management-guidance',
+    phase: 'workspace',
+    order: 40,
+    provide: async (context) => {
+      const data = requiredData(context);
+      if (!data.workspaceId) return null;
+      return (await getWorkspace(data.workspaceId))?.settings?.skills?.managementEnabled
+        ? getHostGuidance().skillManage
+        : null;
+    },
+  },
+];
+
+/** Builds the ordered section list for one scope. Captured through
+ * `PluginContext.buildContext` at composition time so the assembler stays
+ * bound to the scope that owns it. */
+export type ContextSectionBuilder = (
+  data: ContextAssemblyData,
+) => Promise<readonly ProvidedContextSection[]>;
+
+/** The ordered assembler: validates the typed assembly options, asks its
+ * bound scope for the deterministic kernel-ordered sections, and joins them
+ * with the fixed builder's exact '\n\n' separator. */
+export function createOrderedContextAssembler(
+  id: string,
+  buildSections: ContextSectionBuilder,
+): ContextAssembler {
+  return {
+    id,
+    async build(data: ContextAssemblyData): Promise<string> {
+      const validated = validateContextAssemblyData(data);
+      const sections = await buildSections(validated);
+      return sections.map((section) => section.content).join('\n\n');
+    },
+  };
+}
+
+/** One plugin provides the required context-assembler service and registers
+ * every current section. Facade and current compositions install it under
+ * their own deterministic plugin id, so diagnostics stay unambiguous. */
+export function createContextSectionsPlugin(
+  id: string,
+  options: ContextSectionsPluginOptions = {},
+): CapekPlugin<unknown> {
+  const sections: readonly SectionContribution[] = [
+    ...CONTEXT_SECTIONS,
+    ...(options.includeMemorySkillsSections === false ? [] : LEGACY_MEMORY_SKILLS_SECTIONS),
+    ...(options.includeSelfDelegationGuidance === false ? [] : [legacySelfDelegationGuidanceSection]),
+    ...(options.includeSessionSearchGuidance === false ? [] : [legacySessionSearchGuidanceSection]),
+  ];
+  return {
+    id,
+    scope: 'agent',
+    provides: [capekContextAssemblerKey],
+    setup(context: PluginContext) {
+      context.provide(
+        capekContextAssemblerKey,
+        createOrderedContextAssembler(id, (data) => context.buildContext(data)),
+      );
+      for (const section of sections) {
+        context.contributeContext(section);
+      }
+    },
+  };
+}
+
+/** C5 ownership options. Defaults (omitted) keep the legacy full behavior
+ * including the memory, skills, self-delegation, and session-search
+ * guidance sections, so facade and legacy compositions stay byte-identical
+ * to the fixed builder. The current Jean2 composition passes false for all
+ * of them because the memory, skills, subagent, and session-search domain
+ * plugins own those sections there. */
+export interface ContextSectionsPluginOptions {
+  includeMemorySkillsSections?: boolean;
+  includeSelfDelegationGuidance?: boolean;
+  includeSessionSearchGuidance?: boolean;
+}

package/src/plugins/default-agent-driver.ts

@@ -0,0 +1,14 @@
+import type { CapekPlugin } from '../kernel/types';
+import { DefaultAgentDriver } from '../runtime/default-agent-driver';
+import { capekAgentDriverKey } from './service-keys';
+
+export function defaultAgentDriverPlugin(id: string): CapekPlugin<unknown> {
+  return {
+    id,
+    scope: 'agent',
+    provides: [capekAgentDriverKey],
+    setup(context) {
+      context.provide(capekAgentDriverKey, new DefaultAgentDriver());
+    },
+  };
+}

package/src/plugins/facade-plugins.ts

@@ -0,0 +1,129 @@
+/**
+ * Facade agent plugins. One facade agent gets its own agent scope whose
+ * plugins bind the per-agent values the facade used to seed directly. Every
+ * value stays owned by the agent instance, so two simultaneous facade agents
+ * never share storage, configuration, host, tool source, resolver, sandbox
+ * controller, or provider overrides.
+ */
+
+import type { RuntimeConfiguration } from '../configuration/contracts';
+import type { ContextSources } from '../context/sources';
+import type { LoadedTool } from '@capekai/tool';
+import type { CapekPlugin } from '../kernel/types';
+import type { ConnectableProvider } from '../providers/types';
+import type { RuntimeHost } from '../runtime/host';
+import type { SandboxController } from '../sandbox/controller';
+import type { StorageBundle } from '../storage/contracts';
+import type { ToolRegistryResolver } from '../tools/registry';
+import type { WorkspaceToolDiscovery } from '../tools/tool-source';
+import { getSchedulerHost } from '../scheduler/host';
+import { getSessionSearchHost } from '../session-search/host';
+import { createContextSectionsPlugin } from './context-sections';
+import { loadedToolsPlugin } from './loaded-tools';
+import { retryPolicyPlugin } from './retry-policy';
+import { compactionPolicyPlugin } from './compaction-policy';
+import { permissionPolicyPlugin } from './permission-policy';
+import { workspacePolicyPlugin } from './workspace-policy';
+import { toolOutputPolicyPlugin } from './tool-output-policy';
+import { defaultAgentDriverPlugin } from './default-agent-driver';
+import { contributedToolResolverPlugin } from './tool-catalog';
+import {
+  contextSourcesValuePlugin,
+  providerOverridesValuePlugin,
+  runtimeConfigurationValuePlugin,
+  runtimeHostValuePlugin,
+  sandboxControllerValuePlugin,
+  storageValuePlugin,
+  toolResolverValuePlugin,
+  workspaceToolDiscoveryValuePlugin,
+  installedToolRegistryValuePlugin,
+  providerRegistryValuePlugin,
+  schedulerHostValuePlugin,
+  sessionSearchHostValuePlugin,
+} from './value-plugins';
+
+export const FACADE_PROCESS_PLUGIN_IDS = [
+  'facade.provider-registry',
+  'facade.installed-tool-registry',
+  'facade.session-search-host',
+  'facade.scheduler-host',
+] as const;
+
+export function facadeProcessPlugins(): readonly CapekPlugin<unknown>[] {
+  return [
+    providerRegistryValuePlugin('facade.provider-registry'),
+    installedToolRegistryValuePlugin('facade.installed-tool-registry'),
+    sessionSearchHostValuePlugin('facade.session-search-host', getSessionSearchHost()),
+    schedulerHostValuePlugin('facade.scheduler-host', getSchedulerHost()),
+  ];
+}
+
+export interface FacadeScopeValues {
+  storage: StorageBundle;
+  configuration: RuntimeConfiguration;
+  host: RuntimeHost;
+  contextSources: Partial<ContextSources>;
+  workspaceToolDiscovery: WorkspaceToolDiscovery;
+  /** Optional compatibility resolver. When omitted, the facade
+   * composition derives the resolver from the composed scope's effective
+   * contributed tool payloads. The explicit value is the rollback
+   * path and the C2 test seam. */
+  toolResolver?: ToolRegistryResolver;
+  /** Host-supplied plugins appended after the facade's own (external tool
+   * contributions land here). */
+  profilePlugins?: readonly CapekPlugin<unknown>[];
+  /** Convenience: loaded tools contributed by one generated plugin, as with
+   * the former `createAgent({ tools })` option. Equivalent to passing
+   * `loadedToolsPlugin('facade.loaded-tools', tools)` in profilePlugins. */
+  loadedTools?: readonly LoadedTool[];
+  sandboxController: SandboxController;
+  providerOverrides: ReadonlyMap<string, ConnectableProvider>;
+}
+
+export const FACADE_AGENT_PLUGIN_IDS = [
+  'facade.storage',
+  'facade.runtime-configuration',
+  'facade.runtime-host',
+  'facade.agent-driver',
+  'facade.retry-policy',
+  'facade.compaction-policy',
+  'facade.permission-policy',
+  'facade.workspace-policy',
+  'facade.tool-output-policy',
+  'facade.context-sources',
+  'facade.context-sections',
+  'facade.workspace-tool-discovery',
+  'facade.tool-resolver',
+  'facade.sandbox-controller',
+  'facade.provider-overrides',
+] as const;
+
+export function createFacadeAgentPlugins(values: FacadeScopeValues): readonly CapekPlugin<unknown>[] {
+  return [
+    storageValuePlugin('facade.storage', values.storage),
+    runtimeConfigurationValuePlugin('facade.runtime-configuration', values.configuration),
+    runtimeHostValuePlugin('facade.runtime-host', values.host),
+    defaultAgentDriverPlugin('facade.agent-driver'),
+    // C6: the agent scope owns the retry policy (and its circuit state)
+    // instead of the facade's pre-C6 per-agent withRetryCircuitState wrap.
+    retryPolicyPlugin('facade.retry-policy'),
+    compactionPolicyPlugin('facade.compaction-policy'),
+    permissionPolicyPlugin('facade.permission-policy'),
+    workspacePolicyPlugin('facade.workspace-policy'),
+    toolOutputPolicyPlugin('facade.tool-output-policy'),
+    contextSourcesValuePlugin('facade.context-sources', values.contextSources),
+    // Facade context parity: the facade keeps the legacy self-delegation and
+    // session-search guidance sections (the C5 domain plugins own them only
+    // in the current Jean2 composition), so context-sections stays at its
+    // pre-C5 defaults here.
+    createContextSectionsPlugin('facade.context-sections'),
+    workspaceToolDiscoveryValuePlugin('facade.workspace-tool-discovery', values.workspaceToolDiscovery),
+    values.toolResolver === undefined
+      ? contributedToolResolverPlugin('facade.tool-resolver')
+      : toolResolverValuePlugin('facade.tool-resolver', values.toolResolver),
+    sandboxControllerValuePlugin('facade.sandbox-controller', values.sandboxController),
+    providerOverridesValuePlugin('facade.provider-overrides', values.providerOverrides),
+    ...(values.loadedTools?.length ? [loadedToolsPlugin('facade.loaded-tools', values.loadedTools)] : []),
+    ...(values.profilePlugins ?? []),
+  ];
+}

package/src/plugins/goal-domain.ts

@@ -0,0 +1,82 @@
+import { serviceKey } from '../kernel/service-key';
+import type { CapekPlugin, PluginContext } from '../kernel/types';
+import type { Session } from '@capekai/types';
+import type { RuntimeHost } from '../runtime/host';
+import type { StorageBundle } from '../storage/contracts';
+import type { GoalDomainService } from '../goals/service';
+import {
+  evaluateGoalWithDeps,
+  runGoalLoopWithDeps,
+  type GoalEvaluatorDeps,
+  type GoalLoopDeps,
+} from '../goals';
+import {
+  capekOrchestratorSessionKey,
+  capekRuntimeHostKey,
+  capekStorageKey,
+  type OrchestratorSessionContract,
+} from './service-keys';
+
+/**
+ * C5 goal domain plugin. Owns the agent-scoped `capek.goal-domain` service:
+ * goal evaluation and the persistent goal loop run directive over the
+ * scope-captured storage bundle and the shared `capek.orchestrator-session`
+ * contract. No model-facing goal tool exists in the product (goal mode is a
+ * client session directive through `handleChat`), so the domain contributes
+ * no tool and no context section. Live adoption: `core/chat-handler.ts`
+ * resolves this service through `getGoalDomain()`; the unscoped fallback in
+ * `goals/service.ts` keeps the module path for uncomposed consumers.
+ */
+
+export const CURRENT_GOAL_DOMAIN_PLUGIN_ID = 'current.goal-domain';
+
+export type { GoalDomainService };
+
+export const capekGoalDomainKey = serviceKey<GoalDomainService>(
+  'capek.goal-domain',
+  'agent',
+);
+
+function sessionUpdatedBroadcast(host: RuntimeHost): (session: Session) => void {
+  return (session) => {
+    const delivery = {
+      event: { kind: 'session', action: 'updated', session } as const,
+      audience: { scope: 'global' } as const,
+    };
+    host.delivery.observe?.(delivery);
+    host.delivery.emit(delivery);
+  };
+}
+
+export function goalDomainPlugin(id: string): CapekPlugin<unknown> {
+  return {
+    id,
+    scope: 'agent',
+    provides: [capekGoalDomainKey],
+    requires: [capekStorageKey, capekOrchestratorSessionKey, capekRuntimeHostKey],
+    setup(context: PluginContext) {
+      const storage: StorageBundle = context.require(capekStorageKey);
+      const orchestrator: OrchestratorSessionContract = context.require(capekOrchestratorSessionKey);
+      const host: RuntimeHost = context.require(capekRuntimeHostKey);
+
+      const evaluatorDeps: GoalEvaluatorDeps = {
+        listTranscript: (sessionId) => storage.conversation.listMessagesWithParts(sessionId),
+        orchestrator,
+      };
+
+      const loopDeps: GoalLoopDeps = {
+        getSession: (sessionId) => storage.conversation.getSession(sessionId),
+        updateSession: (sessionId, updates) => storage.conversation.updateSession(sessionId, updates),
+        evaluate: (evaluateOptions) => evaluateGoalWithDeps(evaluateOptions, evaluatorDeps),
+        broadcastSessionUpdatedDefault: sessionUpdatedBroadcast(host),
+      };
+
+      const service: GoalDomainService = {
+        evaluateGoal: (options) => evaluateGoalWithDeps(options, evaluatorDeps),
+        runGoalLoop: (options) => runGoalLoopWithDeps(options, loopDeps),
+      };
+
+      context.provide(capekGoalDomainKey, service);
+    },
+  };
+}