@capekai/core 1.0.0

package/src/internal/workspace.ts

@@ -0,0 +1,25 @@
+/**
+ * Public workspace policy entrypoint (`@capekai/core/workspace`).
+ *
+ * Exposes exactly the workspace path policy identities the Jean2 server
+ * consumes through its workspace-paths adapter: containment and
+ * classification algorithms plus the service constructors. Every symbol
+ * resolves to the owning module's identity, identical to the compatibility
+ * barrel. S8a.
+ */
+
+export {
+  expandPath,
+  isInsideUnselectedAdditionalRoot,
+  isPathInside,
+  isPathWithinWorkspace,
+  resolveCandidatePath,
+  resolvePath,
+  resolveRootForQuery,
+  selectEditableRoot,
+} from '../workspace/policy';
+export type {
+  WorkspacePolicy,
+  WorkspacePolicyOptions,
+  WorkspaceService,
+} from '../workspace/contracts';

package/src/kernel/diagnostics.ts

@@ -0,0 +1,249 @@
+/**
+ * Read-only composition diagnostics. Snapshots are built fresh on every
+ * call, contain no plugin options and no service values, and can therefore
+ * be surfaced to support and tests without leaking secrets.
+ */
+
+import type {
+  ContextPhase,
+  ContextSectionContribution,
+  EffectiveContextSection,
+  EffectiveTool,
+  EventListenerContribution,
+  ListenerDiagnostic,
+  PluginStatus,
+  ProvidedContextSection,
+  RunStatus,
+  RunTerminalOutcome,
+  RuntimeScope,
+  ScopeDiagnosticsSnapshot,
+  ScopeStatus,
+  ServiceDiagnostic,
+  ServiceKey,
+  ToolContribution,
+} from './types';
+
+export const CONTEXT_PHASES: readonly ContextPhase[] = [
+  'identity',
+  'preferences',
+  'instructions',
+  'workspace',
+  'capabilities',
+  'task',
+];
+
+export interface LocalToolRegistration {
+  readonly contribution: ToolContribution;
+  readonly pluginId: string;
+}
+
+export interface LocalContextSectionRegistration {
+  readonly contribution: ContextSectionContribution;
+  readonly pluginId: string;
+}
+
+export interface LocalListenerRegistration {
+  readonly contribution: EventListenerContribution;
+  readonly pluginId: string;
+}
+
+
+export interface ResolvedService {
+  readonly key: ServiceKey<unknown>;
+  readonly providerPluginId: string;
+  readonly providerScope: RuntimeScope;
+}
+
+/** Structural view of a scope used by snapshot and listing helpers. */
+export interface ScopeStateView {
+  readonly kind: RuntimeScope;
+  readonly scopeId: string;
+  readonly parent: ScopeStateView | null;
+  readonly status: ScopeStatus;
+  readonly pluginRecords: readonly {
+    readonly id: string;
+    readonly version?: string;
+    readonly scope: RuntimeScope;
+    readonly status: PluginStatus;
+  }[];
+  readonly localServices: ReadonlyMap<string, ResolvedService>;
+  readonly localTools: ReadonlyMap<string, LocalToolRegistration>;
+  readonly localContextSections: ReadonlyMap<string, LocalContextSectionRegistration>;
+  readonly localListeners: ReadonlyMap<string, LocalListenerRegistration>;
+  readonly cleanupBarrierCount: number;
+  readonly runId?: string;
+  readonly runStatus?: RunStatus;
+  readonly runOutcome?: RunTerminalOutcome;
+  resolveServiceRecord(keyId: string): ResolvedService | null;
+}
+
+function chainOf(view: ScopeStateView): ScopeStateView[] {
+  const chain: ScopeStateView[] = [];
+  for (let current: ScopeStateView | null = view; current !== null; current = current.parent) {
+    chain.push(current);
+  }
+  return chain;
+}
+
+function compareIds(a: string, b: string): number {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+export function collectEffectiveServices(view: ScopeStateView): ServiceDiagnostic[] {
+  const services: ServiceDiagnostic[] = [];
+  const seen = new Set<string>();
+  for (const scope of chainOf(view)) {
+    for (const [keyId, registration] of scope.localServices) {
+      if (seen.has(keyId)) continue;
+      seen.add(keyId);
+      services.push({
+        keyId,
+        keyScope: registration.key.scope,
+        providerPluginId: registration.providerPluginId,
+        providerScope: scope.kind,
+      });
+    }
+  }
+  return services;
+}
+
+export function collectEffectiveTools(view: ScopeStateView): EffectiveTool[] {
+  const tools: EffectiveTool[] = [];
+  const seen = new Set<string>();
+  for (const scope of chainOf(view)) {
+    for (const [toolId, registration] of scope.localTools) {
+      if (seen.has(toolId)) continue;
+      seen.add(toolId);
+      const hiddenReasons: string[] = [];
+      const explicit = registration.contribution.visibility;
+      if (explicit?.visible === false) {
+        hiddenReasons.push(explicit.reason ?? 'explicitly hidden by tool visibility');
+      }
+      for (const capability of registration.contribution.requiredCapabilities ?? []) {
+        const resolved = view.resolveServiceRecord(capability.id);
+        if (resolved === null || resolved.key.scope !== capability.scope) {
+          hiddenReasons.push(`missing required capability '${capability.id}'`);
+        }
+      }
+      tools.push({
+        id: toolId,
+        order: registration.contribution.order ?? 0,
+        definition: registration.contribution.definition,
+        ...(registration.contribution.payload !== undefined
+          ? { payload: registration.contribution.payload }
+          : {}),
+        pluginId: registration.pluginId,
+        visible: hiddenReasons.length === 0,
+        hiddenReasons,
+      });
+    }
+  }
+  tools.sort((a, b) => (
+    a.order - b.order
+    || compareIds(a.pluginId, b.pluginId)
+    || compareIds(a.id, b.id)
+  ));
+  return tools;
+}
+
+export function collectEffectiveContextSections(
+  view: ScopeStateView,
+): EffectiveContextSection[] {
+  const sections: EffectiveContextSection[] = [];
+  const seen = new Set<string>();
+  for (const scope of chainOf(view)) {
+    for (const [sectionId, registration] of scope.localContextSections) {
+      if (seen.has(sectionId)) continue;
+      seen.add(sectionId);
+      sections.push({
+        id: sectionId,
+        phase: registration.contribution.phase,
+        order: registration.contribution.order,
+        pluginId: registration.pluginId,
+        scopeKind: scope.kind,
+      });
+    }
+  }
+  sections.sort((a, b) => (
+    CONTEXT_PHASES.indexOf(a.phase) - CONTEXT_PHASES.indexOf(b.phase)
+    || a.order - b.order
+    || compareIds(a.pluginId, b.pluginId)
+    || compareIds(a.id, b.id)
+  ));
+  return sections;
+}
+
+function collectEffectiveListeners(view: ScopeStateView): ListenerDiagnostic[] {
+  const listeners: ListenerDiagnostic[] = [];
+  const seen = new Set<string>();
+  for (const scope of chainOf(view)) {
+    for (const [listenerId, registration] of scope.localListeners) {
+      if (seen.has(listenerId)) continue;
+      seen.add(listenerId);
+      listeners.push({
+        id: listenerId,
+        eventTypes: registration.contribution.eventTypes,
+        pluginId: registration.pluginId,
+        scopeKind: scope.kind,
+      });
+    }
+  }
+  return listeners;
+}
+
+
+export function buildSnapshot(view: ScopeStateView): ScopeDiagnosticsSnapshot {
+  const runFields = view.runId !== undefined
+    ? { runId: view.runId, runStatus: view.runStatus, runOutcome: view.runOutcome }
+    : {};
+  return {
+    scopeId: view.scopeId,
+    kind: view.kind,
+    parentKind: view.parent?.kind ?? null,
+    status: view.status,
+    plugins: view.pluginRecords.map((record) => ({
+      id: record.id,
+      version: record.version,
+      scope: record.scope,
+      status: record.status,
+    })),
+    services: collectEffectiveServices(view),
+    tools: collectEffectiveTools(view).map(({ definition: _definition, payload: _payload, ...tool }) => tool),
+    contextSections: collectEffectiveContextSections(view).map((section) => ({
+      id: section.id,
+      phase: section.phase,
+      order: section.order,
+      pluginId: section.pluginId,
+      scopeKind: section.scopeKind,
+    })),
+    listeners: collectEffectiveListeners(view),
+    cleanupBarrierCount: view.cleanupBarrierCount,
+    ...runFields,
+  };
+}
+
+/** Assembles effective context sections in deterministic order. Null
+ * sections are omitted without shifting the other sections. The optional
+ * `data` is passed through to every provider as `ContextBuildContext.data`. */
+export async function buildContextSections(
+  view: ScopeStateView,
+  data?: unknown,
+): Promise<ProvidedContextSection[]> {
+  const chain = chainOf(view);
+  const provided: ProvidedContextSection[] = [];
+  for (const section of collectEffectiveContextSections(view)) {
+    const owningScope = chain.find((scope) => scope.kind === section.scopeKind);
+    const contribution = owningScope?.localContextSections.get(section.id)?.contribution;
+    if (contribution === undefined) {
+      continue;
+    }
+    const content = await contribution.provide({ kind: section.scopeKind, data });
+    if (content === null) {
+      continue;
+    }
+    provided.push({ id: section.id, phase: section.phase, content });
+  }
+  return provided;
+}

package/src/kernel/errors.ts

@@ -0,0 +1,120 @@
+/**
+ * Kernel error types. Validation and lifecycle failures are typed so callers
+ * can distinguish malformed composition from runtime behavior.
+ */
+
+import type { KernelEventType } from './types';
+
+export function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export class KernelError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+/** Composition rejected before activation: nothing ran. */
+export class CompositionError extends KernelError {}
+
+export class DuplicatePluginError extends CompositionError {}
+
+export class MalformedPluginError extends CompositionError {}
+
+export class ScopeValidationError extends CompositionError {}
+
+/** A child scope attempted to provide a service already effective in a
+ * parent scope. Child scopes do not replace parent services. */
+export class ServiceCollisionError extends CompositionError {}
+
+export class DuplicateProviderError extends CompositionError {}
+
+export class InvalidOverrideError extends CompositionError {}
+
+export class MissingDependencyError extends CompositionError {}
+
+export class DependencyCycleError extends CompositionError {}
+
+/** A contribution id was registered twice within one scope. */
+export class DuplicateContributionError extends CompositionError {}
+
+export interface DisposalFailure {
+  readonly pluginId: string;
+  readonly error: unknown;
+}
+
+/** Aggregated errors from reverse disposal. Every resource is still
+ * attempted even when earlier disposers fail. */
+export class DisposalError extends KernelError {
+  readonly failures: readonly DisposalFailure[];
+
+  constructor(failures: readonly DisposalFailure[]) {
+    const details = failures
+      .map((failure) => `plugin '${failure.pluginId}': ${errorMessage(failure.error)}`)
+      .join('; ');
+    super(`disposal failed with ${failures.length} error(s): ${details}`);
+    this.failures = failures;
+  }
+}
+
+/** Setup failed. Completed registrations were rolled back in reverse order.
+ * The original setup error and any disposal errors are both preserved. */
+export class ActivationError extends KernelError {
+  readonly pluginId: string;
+  override readonly cause: unknown;
+  readonly disposalErrors: readonly DisposalFailure[];
+
+  constructor(
+    pluginId: string,
+    cause: unknown,
+    disposalErrors: readonly DisposalFailure[],
+  ) {
+    const rollback = disposalErrors.length > 0
+      ? `; ${disposalErrors.length} disposal error(s) during rollback`
+      : '';
+    super(`plugin '${pluginId}' setup failed: ${errorMessage(cause)}${rollback}`);
+    this.pluginId = pluginId;
+    this.cause = cause;
+    this.disposalErrors = disposalErrors;
+  }
+}
+
+/** A lifecycle call arrived in the wrong state (for example start twice). */
+export class LifecycleError extends KernelError {}
+
+export interface ListenerFailure {
+  readonly listenerId: string;
+  readonly error: unknown;
+}
+
+/** One or more event listeners threw during an awaited emit. Remaining
+ * listeners were still dispatched. */
+export class EventEmitError extends KernelError {
+  readonly eventType: KernelEventType;
+  readonly failures: readonly ListenerFailure[];
+
+  constructor(eventType: KernelEventType, failures: readonly ListenerFailure[]) {
+    const details = failures
+      .map((failure) => `listener '${failure.listenerId}': ${errorMessage(failure.error)}`)
+      .join('; ');
+    super(`event '${eventType}' dispatch failed: ${details}`);
+    this.eventType = eventType;
+    this.failures = failures;
+  }
+}
+
+/** Errors collected while a run moved from terminal to disposed. Cleanup and
+ * disposal still ran to completion before this error was raised. */
+export class RunTerminalError extends KernelError {
+  readonly runId: string;
+  readonly errors: readonly unknown[];
+
+  constructor(runId: string, errors: readonly unknown[]) {
+    const details = errors.map(errorMessage).join('; ');
+    super(`run '${runId}' terminal cleanup had ${errors.length} error(s): ${details}`);
+    this.runId = runId;
+    this.errors = errors;
+  }
+}

package/src/kernel/events.ts

@@ -0,0 +1,82 @@
+/**
+ * Simple awaited emit. Listeners observe typed runtime events; the kernel
+ * dispatches each listener sequentially and awaits it. There is no serial
+ * or waterfall interception framework: listeners cannot stop or replace
+ * events.
+ */
+
+import { EventEmitError, MalformedPluginError, type ListenerFailure } from './errors';
+import type {
+  EventListenerContribution,
+  KernelEvent,
+  KernelEventType,
+} from './types';
+
+const KNOWN_EVENT_TYPES = new Set<string>(['run:started', 'run:terminal', 'run:disposed']);
+
+export interface ListenerRegistration {
+  readonly contribution: EventListenerContribution;
+  readonly pluginId: string;
+}
+
+export function validateListener(contribution: EventListenerContribution): void {
+  if (typeof contribution !== 'object' || contribution === null) {
+    throw new MalformedPluginError('listener contribution must be an object');
+  }
+  if (typeof contribution.id !== 'string' || contribution.id.length === 0) {
+    throw new MalformedPluginError('listener contribution id must be a non-empty string');
+  }
+  if (!Array.isArray(contribution.eventTypes)) {
+    throw new MalformedPluginError(
+      `listener '${contribution.id}' eventTypes must be an array`,
+    );
+  }
+  if (contribution.eventTypes.length === 0) {
+    throw new MalformedPluginError(
+      `listener '${contribution.id}' must declare at least one event type`,
+    );
+  }
+  for (const eventType of contribution.eventTypes) {
+    if (!KNOWN_EVENT_TYPES.has(eventType)) {
+      throw new MalformedPluginError(
+        `listener '${contribution.id}' declares unknown event type '${String(eventType)}'`,
+      );
+    }
+  }
+  if (typeof contribution.handle !== 'function') {
+    throw new MalformedPluginError(
+      `listener '${contribution.id}' must provide a handle function`,
+    );
+  }
+}
+
+export interface ListenerScopeView {
+  readonly listeners: readonly ListenerRegistration[];
+}
+
+/** Dispatches an event to every matching listener in a snapshot chain,
+ * child scope first then ancestors. All listeners run even when earlier
+ * ones throw; failures are aggregated into EventEmitError after dispatch
+ * completes. */
+export async function dispatchEvent(
+  chain: readonly ListenerScopeView[],
+  event: KernelEvent,
+): Promise<void> {
+  const failures: ListenerFailure[] = [];
+  for (const scope of chain) {
+    for (const registration of scope.listeners) {
+      const { contribution } = registration;
+      if (!contribution.eventTypes.includes(event.type as KernelEventType)) {
+        continue;
+      }
+      try {
+        await contribution.handle(event);
+      } catch (err) {
+        failures.push({ listenerId: contribution.id, error: err });
+      }
+    }
+  }
+  if (failures.length > 0) {
+    throw new EventEmitError(event.type, failures);
+  }
+}

package/src/kernel/index.ts

@@ -0,0 +1,72 @@
+/**
+ * Internal kernel barrel. Tests import from here; the package root index
+ * intentionally does not re-export the kernel.
+ */
+
+export { createAgentScope, createProcessScope, createRunScope } from './kernel';
+export { serviceKey } from './service-key';
+export { dispatchEvent, validateListener } from './events';
+export {
+  ActivationError,
+  CompositionError,
+  DependencyCycleError,
+  DisposalError,
+  DuplicateContributionError,
+  DuplicatePluginError,
+  DuplicateProviderError,
+  EventEmitError,
+  InvalidOverrideError,
+  KernelError,
+  LifecycleError,
+  MalformedPluginError,
+  MissingDependencyError,
+  RunTerminalError,
+  ScopeValidationError,
+  ServiceCollisionError,
+  errorMessage,
+} from './errors';
+export type {
+  DisposalFailure,
+  ListenerFailure,
+} from './errors';
+export type {
+  AgentScopeHandle,
+  CapekPlugin,
+  CleanupBarrier,
+  CompositionDiagnostics,
+  ContextBuildContext,
+  ContextPhase,
+  ContextSectionContribution,
+  ContextSectionDiagnostic,
+  Disposable,
+  EffectiveContextSection,
+  EffectiveTool,
+  EventListenerContribution,
+  KernelEvent,
+  KernelEventMap,
+  KernelEventType,
+  ListenerDiagnostic,
+  PluginContext,
+  PluginDiagnostic,
+  PluginOptionsMap,
+  ProcessScopeHandle,
+  ProvidedContextSection,
+  RunCancellation,
+  RunDisposedEvent,
+  RunScopeHandle,
+  RunStartedEvent,
+  RunStatus,
+  RunTerminalEvent,
+  RunTerminalOutcome,
+  RuntimeScope,
+  ScopeDiagnosticsSnapshot,
+  ScopeHandle,
+  ScopeStatus,
+  ServiceDiagnostic,
+  ServiceKey,
+  ServiceOverride,
+  ToolContribution,
+  ToolDefinition,
+  ToolDiagnostic,
+  ToolVisibility,
+} from './types';

package/src/kernel/kernel.ts

@@ -0,0 +1,62 @@
+/**
+ * Kernel creation API. This is an internal composition entry point used by
+ * the C2 plugin layer. The kernel is not exported from the package root;
+ * `createAgent()` composes through `src/plugins`, never by importing the
+ * kernel directly.
+ */
+
+import { LifecycleError } from './errors';
+import {
+  AgentScope,
+  ProcessScope,
+  agentScopeBrand,
+  processScopeBrand,
+} from './scope';
+import type {
+  AgentScopeHandle,
+  CapekPlugin,
+  PluginOptionsMap,
+  ProcessScopeHandle,
+  RunScopeHandle,
+} from './types';
+
+/** Scope parents are validated through brands registered in the global
+ * symbol registry (Symbol.for), so a parent scope created through a
+ * duplicate module instance still carries the same brand. The check
+ * validates the parent link structurally across module instances; it is
+ * not a security boundary against code that can read the global symbol
+ * registry. */
+function carriesBrand(target: unknown, brand: symbol): boolean {
+  return typeof target === 'object' && target !== null
+    && (target as Record<symbol, unknown>)[brand] === true;
+}
+
+export async function createProcessScope(
+  plugins: readonly CapekPlugin<unknown>[],
+  options?: PluginOptionsMap,
+): Promise<ProcessScopeHandle> {
+  return ProcessScope.create(plugins, options);
+}
+
+export async function createAgentScope(
+  parent: ProcessScopeHandle,
+  plugins: readonly CapekPlugin<unknown>[],
+  options?: PluginOptionsMap,
+): Promise<AgentScopeHandle> {
+  if (!carriesBrand(parent, processScopeBrand)) {
+    throw new LifecycleError('an agent scope requires a process scope parent');
+  }
+  return (parent as ProcessScope).createAgentScope(plugins, options);
+}
+
+export async function createRunScope(
+  parent: AgentScopeHandle,
+  runId: string,
+  plugins: readonly CapekPlugin<unknown>[],
+  options?: PluginOptionsMap,
+): Promise<RunScopeHandle> {
+  if (!carriesBrand(parent, agentScopeBrand)) {
+    throw new LifecycleError('a run scope requires an agent scope parent');
+  }
+  return (parent as AgentScope).createRunScope(runId, plugins, options);
+}

package/src/kernel/lifecycle.ts

@@ -0,0 +1,72 @@
+/**
+ * Activation and disposal execution. Activation follows the deterministic
+ * plan; on failure, completed registrations roll back in reverse order with
+ * both the setup error and disposal errors preserved. Normal disposal runs
+ * in reverse activation order and aggregates failures.
+ */
+
+import {
+  ActivationError,
+  DisposalError,
+  type DisposalFailure,
+} from './errors';
+import { enforceDeclaredProvides, isDisposable, type PluginRecord } from './plugin';
+import type { PluginOptionsMap } from './types';
+
+export async function activateRecords(
+  records: readonly PluginRecord[],
+  order: readonly string[],
+  options: PluginOptionsMap,
+): Promise<void> {
+  const byId = new Map(records.map((record) => [record.id, record]));
+  const completed: PluginRecord[] = [];
+  for (const id of order) {
+    const record = byId.get(id) as PluginRecord;
+    try {
+      const result = await record.plugin.setup(record.context, options[id]);
+      if (isDisposable(result)) {
+        record.returnedDisposable = result;
+      }
+      enforceDeclaredProvides(record);
+      record.status = 'active';
+      completed.push(record);
+    } catch (err) {
+      record.status = 'failed';
+      const failures = await disposeRecords([...completed, record]);
+      throw new ActivationError(record.id, err, failures);
+    }
+  }
+}
+
+/** Disposes records in reverse order. Every disposer is attempted even when
+ * earlier disposers throw. Returns the collected failures. */
+export async function disposeRecords(
+  records: readonly PluginRecord[],
+): Promise<DisposalFailure[]> {
+  const failures: DisposalFailure[] = [];
+  for (const record of [...records].reverse()) {
+    if (record.status === 'disposed') continue;
+    for (const disposer of [...record.context.disposers].reverse()) {
+      try {
+        await disposer.dispose();
+      } catch (err) {
+        failures.push({ pluginId: record.id, error: err });
+      }
+    }
+    if (record.returnedDisposable !== undefined) {
+      try {
+        await record.returnedDisposable.dispose();
+      } catch (err) {
+        failures.push({ pluginId: record.id, error: err });
+      }
+    }
+    record.status = 'disposed';
+  }
+  return failures;
+}
+
+export function throwDisposalError(failures: readonly DisposalFailure[]): void {
+  if (failures.length > 0) {
+    throw new DisposalError(failures);
+  }
+}