@capekai/core 1.0.0

package/src/plugins/legacy-system-message.ts

@@ -0,0 +1,152 @@
+import type { Preconfig } from '@capekai/types';
+import { loadMemoryInstructions } from '../memory';
+import { selfDelegationGuidance } from '../subagent/guidance';
+import {
+  buildWorkspaceSystemPrompt,
+  formatInstructions,
+  getAgentDirectory,
+  loadInstructions,
+  readAgentMemoryFile,
+} from '../context';
+import { getWorkspace } from '../storage/runtime';
+import { getHostGuidance } from '../runtime/host-guidance';
+import { getHostLayout } from '../runtime/host-layout';
+import {
+  validateContextAssemblyData,
+  type ContextAssembler,
+  type ContextAssemblyData,
+} from '../context/assembler';
+import type { ContextSectionContribution } from '../kernel/types';
+
+/**
+ * Fixed system-message builder, byte-frozen as the C3 legacy adapter.
+ *
+ * C3 replaced this builder with ordered context contributions, but the fixed
+ * implementation stays available through `internal/execution` for migration
+ * and serves as the reference against which ordered assembly is verified
+ * byte-for-byte. The section guidance constants below are shared with the
+ * ordered contributions so both paths emit identical bytes.
+ */
+
+export interface SystemMessageOptions {
+  preconfig: Preconfig;
+  workspacePath?: string;
+  workspaceId?: string;
+  additionalPaths?: string[];
+  selfDelegationAvailable?: boolean;
+}
+
+/** The fixed builder behind the ContextAssembler contract. Installed as the
+ * default assembler so consumers that run outside a composed agent scope
+ * (the current Jean2 server path) keep the exact pre-C3 behavior until they
+ * adopt the ordered composition. */
+export const fixedBuilderContextAssembler: ContextAssembler = {
+  id: 'fixed-legacy-adapter',
+  build: (data) => buildSystemMessage(data),
+};
+
+/** The legacy session-search guidance contribution, kept for facade and
+ * legacy compositions that reproduce the fixed builder byte-for-byte. The
+ * C5 domain plugin owns this section in the current Jean2 composition;
+ * `createContextSectionsPlugin` includes it only when its
+ * `includeSessionSearchGuidance` option stays at the legacy default. */
+export const legacySessionSearchGuidanceSection: ContextSectionContribution<ContextAssemblyData> = {
+  id: 'session-search-guidance',
+  phase: 'workspace',
+  order: 50,
+  provide: async (context) => {
+    const data = validateContextAssemblyData(context.data);
+    if (!data.workspaceId) return null;
+    return (await getWorkspace(data.workspaceId))?.settings?.sessionSearch?.enabled
+      ? getHostGuidance().sessionSearch
+      : null;
+  },
+};
+
+export const AGENT_MEMORY_SKILLS_GUIDANCE = `You have personal memory and skills that travel with you across all workspaces.
+
+MEMORY:
+- Use "memory" (workspace) for facts about THIS project (repo conventions, build commands, project-specific patterns).
+- Use "agent_memory" (personal) for cross-project knowledge: reusable patterns, techniques, pitfalls, and user preferences that apply everywhere.
+- Save to agent_memory when: you complete a complex multi-step task, the user corrects your approach, you discover a pattern useful beyond this project, or you debug through errors.
+
+SKILLS:
+- Use "skill_manage" for procedures specific to THIS workspace.
+- Use "agent_skill_manage" for personal workflows you've refined across projects.
+
+Before saving, use list to check existing entries and avoid duplicates.`;
+
+/** The legacy self-delegation guidance contribution, kept for facade and
+ * legacy compositions that reproduce the fixed builder byte-for-byte. The
+ * C5 subagent domain plugin owns this section in the current Jean2 and
+ * facade compositions; `createContextSectionsPlugin` includes it only when
+ * its `includeSelfDelegationGuidance` option stays at the legacy default. */
+export const legacySelfDelegationGuidanceSection: ContextSectionContribution<ContextAssemblyData> = {
+  id: 'self-delegation',
+  phase: 'identity',
+  order: 50,
+  provide: (context) => {
+    const data = validateContextAssemblyData(context.data);
+    return data.selfDelegationAvailable ? selfDelegationGuidance(data.preconfig.id) : null;
+  },
+};
+
+export async function buildSystemMessage(options: SystemMessageOptions): Promise<string> {
+  const { preconfig, workspacePath, workspaceId, additionalPaths } = options;
+
+  let systemMessage = preconfig.systemPrompt || '';
+
+  // Inject agent memory layers if this is an agent
+  const agentDir = await getAgentDirectory(preconfig.id);
+  if (agentDir) {
+    const agentUserMemory = await readAgentMemoryFile(preconfig.id, 'USER.md');
+    if (agentUserMemory) {
+      systemMessage = `<agent_user_preferences>\n${agentUserMemory}\n</agent_user_preferences>\n\n` + systemMessage;
+    }
+    const agentMemory = await readAgentMemoryFile(preconfig.id, 'MEMORY.md');
+    if (agentMemory) {
+      systemMessage = `<agent_memory>\n${agentMemory}\n</agent_memory>\n\n` + systemMessage;
+    }
+
+    systemMessage = systemMessage + '\n\n' + getHostGuidance().agentMemorySkills;
+  }
+
+  if (options.selfDelegationAvailable) {
+    systemMessage = systemMessage + '\n\n' + selfDelegationGuidance(preconfig.id);
+  }
+
+  // Add instructions (global first, then project)
+  const instructions = await loadInstructions(workspacePath);
+  const instructionsSection = formatInstructions(instructions);
+  if (instructionsSection) {
+    systemMessage = systemMessage + '\n\n' + instructionsSection;
+  }
+
+  // Add workspace context
+  if (workspacePath) {
+    const workspaceContext = buildWorkspaceSystemPrompt(workspacePath, additionalPaths);
+    systemMessage = systemMessage + '\n\n' + workspaceContext;
+  }
+
+  // Add workspace-gated guidance sections
+  if (workspaceId) {
+    const workspace = await getWorkspace(workspaceId);
+    if (workspace?.settings?.memory?.enabled && workspacePath) {
+      const memorySection = await loadMemoryInstructions(getHostLayout().workspaceMemoryDir(workspacePath));
+      if (memorySection) {
+        systemMessage = systemMessage + '\n\n' + memorySection;
+      }
+      systemMessage = systemMessage + '\n\n' + getHostGuidance().memory;
+    }
+
+    if (workspace?.settings?.skills?.managementEnabled) {
+      systemMessage = systemMessage + '\n\n' + getHostGuidance().skillManage;
+    }
+
+    if (workspace?.settings?.sessionSearch?.enabled) {
+      systemMessage = systemMessage + '\n\n' + getHostGuidance().sessionSearch;
+    }
+  }
+
+  return systemMessage;
+}

package/src/plugins/loaded-tools.ts

@@ -0,0 +1,23 @@
+import type { LoadedTool } from '@capekai/tool';
+import type { CapekPlugin, ToolDefinition } from '../kernel/types';
+
+/** One agent plugin contributing the given loaded tools as visible tool
+ * contributions carrying their execution payloads, in array order. This is
+ * the plugin behind the former `createAgent({ tools })` option; compose it
+ * directly into your agent scope's plugin list. */
+export function loadedToolsPlugin(id: string, tools: readonly LoadedTool[]): CapekPlugin<unknown> {
+  return {
+    id,
+    scope: 'agent',
+    setup(context) {
+      tools.forEach((loaded, index) => {
+        context.contributeTool({
+          id: `${id}.${loaded.definition.name}`,
+          order: 1000 + index,
+          definition: loaded.definition as unknown as ToolDefinition,
+          payload: loaded,
+        });
+      });
+    },
+  };
+}

package/src/plugins/memory-domain.ts

@@ -0,0 +1,264 @@
+import type { PermissionRiskLevel } from '@capekai/tool';
+import { serviceKey } from '../kernel/service-key';
+import type {
+  CapekPlugin,
+  ContextSectionContribution,
+  PluginContext,
+  ToolDefinition as KernelToolDefinition,
+} from '../kernel/types';
+import {
+  DOMAIN_TOOL_PAYLOAD_FIELD,
+  registerDomainToolFallback,
+  type DomainToolPayload,
+} from '../runtime/domain-tool-source';
+import { validateContextAssemblyData, type ContextAssemblyData } from '../context/assembler';
+import type { ContextSources } from '../context/sources';
+import {
+  executeMemoryTool,
+  memoryToolDefinition,
+  loadMemoryInstructions,
+} from '../memory';
+import type { StorageBundle } from '../storage/contracts';
+import { getHostGuidance } from '../runtime/host-guidance';
+import { getHostLayout } from '../runtime/host-layout';
+import { capekContextSourcesKey, capekStorageKey } from './service-keys';
+
+/**
+ * C5 memory domain plugin. Owns the agent-scoped memory service: the
+ * workspace `memory` tool payload, the agent `agent_memory` tool payload,
+ * and the memory context sections (agent-memory, agent-user-preferences,
+ * memory-skills-guidance, workspace-memory, memory-guidance). Tool building
+ * stays in the core tool builders over the generic contributed-domain-tool
+ * seam; the payloads read only the build context the builders capture
+ * (workspace path, permission risk, agent directory), never module globals.
+ * The unscoped fallback installs explicitly, never at module load.
+ */
+
+export const CURRENT_MEMORY_DOMAIN_PLUGIN_ID = 'current.memory-domain';
+export const MEMORY_TOOL_CONTRIBUTION_ID = 'memory.memory';
+export const MEMORY_TOOL_CONTRIBUTION_ORDER = 665;
+export const AGENT_MEMORY_TOOL_CONTRIBUTION_ID = 'memory.agent_memory';
+export const AGENT_MEMORY_TOOL_CONTRIBUTION_ORDER = 800;
+
+export interface MemoryDomainService {
+  readonly tools: readonly DomainToolPayload[];
+}
+
+export const capekMemoryDomainKey = serviceKey<MemoryDomainService>(
+  'capek.memory-domain',
+  'agent',
+);
+
+export function createMemoryToolPayload(): DomainToolPayload {
+  return {
+    name: memoryToolDefinition.name,
+    description: memoryToolDefinition.description,
+    inputSchema: memoryToolDefinition.inputSchema,
+    display: { summary: '{action} {target}' },
+    visualize: (_input, result) => {
+      const r = result as { action?: string; target?: string; usage?: { chars?: number; limit?: number }; entries?: string[] };
+      if (r.action === 'list') {
+        const count = Array.isArray(r.entries) ? r.entries.length : 0;
+        const usage = r.usage ? `${r.usage.chars ?? 0}/${r.usage.limit ?? 0} chars` : '';
+        return {
+          type: 'none',
+          badge: [`${count} entr${count === 1 ? 'y' : 'ies'}`, usage].filter(Boolean).join(' · '),
+          message: `Memory (${r.target ?? 'memory'})`,
+        };
+      }
+      return { type: 'none', message: String(result.title ?? 'Memory updated') };
+    },
+    execute: async (input, context) => {
+      const workspacePath = context.workspacePath as string;
+      const risk = (context.permissionRisk ?? 'none') as PermissionRiskLevel;
+      const result = await executeMemoryTool(
+        input,
+        getHostLayout().workspaceMemoryDir(workspacePath),
+        risk,
+        context.ask,
+      );
+      if (!result.success) {
+        return {
+          error: result.error ?? 'Memory operation failed',
+          ...(result.entries ? { entries: result.entries } : {}),
+          ...(result.usage ? { usage: result.usage } : {}),
+        };
+      }
+      const r = result.result!;
+      return {
+        title: r.action === 'list' ? `Memory list (${r.target})` : 'Memory updated',
+        ...r,
+      };
+    },
+  };
+}
+
+export function createAgentMemoryToolPayload(): DomainToolPayload {
+  return {
+    name: 'agent_memory',
+    description: `Persist YOUR personal knowledge that travels with you across all workspaces.
+
+Use target="user" for cross-workspace user preferences (how this person likes to work).
+Use target="memory" for accumulated work knowledge (lessons, patterns, techniques from any project).
+
+This is YOUR personal memory. It is separate from the workspace memory tool.
+- Use "memory" (workspace) for project-specific facts about the current codebase.
+- Use "agent_memory" (this tool) for cross-project knowledge that applies everywhere.
+
+Actions:
+- list: Read current entries and char usage. Requires target only.
+- add: Append a new bullet entry. Requires content.
+- replace: Find an entry by oldText substring and replace it.
+- remove: Find an entry by oldText substring and remove it.
+
+Character limits: user=1500, memory=2500. Keep entries compact.`,
+    inputSchema: memoryToolDefinition.inputSchema,
+    display: { summary: '{action} {target}' },
+    visualize: (_input, result) => {
+      const r = result as { action?: string; target?: string; entries?: string[] };
+      if (r.action === 'list') {
+        const count = Array.isArray(r.entries) ? r.entries.length : 0;
+        return {
+          type: 'none',
+          badge: `${count} entr${count === 1 ? 'y' : 'ies'}`,
+          message: `Agent memory (${r.target ?? 'memory'})`,
+        };
+      }
+      return { type: 'none', message: String(result.title ?? 'Agent memory updated') };
+    },
+    execute: async (input, context) => {
+      const result = await executeMemoryTool(input, context.agentDir as string, 'none');
+      if (!result.success) {
+        return { error: result.error ?? 'Agent memory operation failed' };
+      }
+      const r = result.result!;
+      return {
+        title: r.action === 'list' ? `Agent memory list (${r.target})` : 'Agent memory updated',
+        ...r,
+      };
+    },
+  };
+}
+
+/** Explicitly installs the unscoped legacy fallbacks. Called by the Jean2
+ * compatibility bindings installation (server bootstrap) and by focused
+ * tests; no module-load registration exists. */
+export function installMemoryToolFallback(): void {
+  registerDomainToolFallback('memory', createMemoryToolPayload());
+  registerDomainToolFallback('agent_memory', createAgentMemoryToolPayload());
+}
+
+type MemorySectionContribution = ContextSectionContribution<ContextAssemblyData>;
+
+function agentMemorySections(
+  sources: Partial<ContextSources>,
+  guidance: string,
+): readonly MemorySectionContribution[] {
+  return [
+    {
+      id: 'agent-memory',
+      phase: 'identity',
+      order: 10,
+      provide: async (build) => {
+        const data = validateContextAssemblyData(build.data);
+        const agentDir = await sources.agents?.getDirectory(data.preconfig.id);
+        if (!agentDir) return null;
+        const memory = await sources.agents?.readMemoryFile(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 (build) => {
+        const data = validateContextAssemblyData(build.data);
+        const agentDir = await sources.agents?.getDirectory(data.preconfig.id);
+        if (!agentDir) return null;
+        const memory = await sources.agents?.readMemoryFile(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 (build) => {
+        const data = validateContextAssemblyData(build.data);
+        const agentDir = await sources.agents?.getDirectory(data.preconfig.id);
+        return agentDir ? guidance : null;
+      },
+    },
+  ];
+}
+
+function workspaceMemorySections(storage: StorageBundle): readonly MemorySectionContribution[] {
+  return [
+    {
+      id: 'workspace-memory',
+      phase: 'workspace',
+      order: 20,
+      provide: async (build) => {
+        const data = validateContextAssemblyData(build.data);
+        if (!data.workspaceId) return null;
+        const workspace = await storage.workspaces.get(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 (build) => {
+        const data = validateContextAssemblyData(build.data);
+        if (!data.workspaceId) return null;
+        const workspace = await storage.workspaces.get(data.workspaceId);
+        return workspace?.settings?.memory?.enabled && data.workspacePath ? getHostGuidance().memory : null;
+      },
+    },
+  ];
+}
+
+export function memoryDomainPlugin(id: string): CapekPlugin<unknown> {
+  return {
+    id,
+    scope: 'agent',
+    provides: [capekMemoryDomainKey],
+    requires: [capekStorageKey, capekContextSourcesKey],
+    setup(context: PluginContext) {
+      const storage: StorageBundle = context.require(capekStorageKey);
+      const sources: Partial<ContextSources> = context.require(capekContextSourcesKey);
+
+      const service: MemoryDomainService = {
+        tools: [createMemoryToolPayload(), createAgentMemoryToolPayload()],
+      };
+
+      context.provide(capekMemoryDomainKey, service);
+      for (const payload of service.tools) {
+        context.contributeTool({
+          id: payload.name === 'memory'
+            ? MEMORY_TOOL_CONTRIBUTION_ID
+            : AGENT_MEMORY_TOOL_CONTRIBUTION_ID,
+          order: payload.name === 'memory'
+            ? MEMORY_TOOL_CONTRIBUTION_ORDER
+            : AGENT_MEMORY_TOOL_CONTRIBUTION_ORDER,
+          definition: {
+            name: payload.name,
+            description: payload.description,
+            inputSchema: payload.inputSchema,
+            timeout: 10000,
+            [DOMAIN_TOOL_PAYLOAD_FIELD]: payload,
+          } as KernelToolDefinition,
+          requiredCapabilities: [capekMemoryDomainKey],
+        });
+      }
+      for (const section of agentMemorySections(sources, getHostGuidance().agentMemorySkills)) {
+        context.contributeContext(section);
+      }
+      for (const section of workspaceMemorySections(storage)) {
+        context.contributeContext(section);
+      }
+    },
+  };
+}

package/src/plugins/orchestrator-session.ts

@@ -0,0 +1,29 @@
+import type { CapekPlugin, PluginContext } from '../kernel/types';
+import { runOrchestratorSession } from '../workflow/orchestrator-session';
+import {
+  capekOrchestratorSessionKey,
+  type OrchestratorSessionContract,
+} from './service-keys';
+
+/**
+ * C5 provider for the shared workflow/goals orchestrator model-turn
+ * contract (`capek.orchestrator-session`). Wraps the current implementation
+ * at `workflow/orchestrator-session.ts` with its exact function identity, so
+ * the workflow domain plugin and, next slice, the goals domain plugin
+ * consume the same named service without owning workflow code. The provider
+ * is a composition bridge; its workflow-domain import is pinned by the
+ * `plugins-no-workflow-ownership` boundary rule.
+ */
+export function orchestratorSessionProviderPlugin(id: string): CapekPlugin<unknown> {
+  return {
+    id,
+    scope: 'agent',
+    provides: [capekOrchestratorSessionKey],
+    setup(context: PluginContext) {
+      const contract: OrchestratorSessionContract = {
+        run: runOrchestratorSession,
+      };
+      context.provide(capekOrchestratorSessionKey, contract);
+    },
+  };
+}

package/src/plugins/permission-policy.ts

@@ -0,0 +1,49 @@
+import type { CapekPlugin, PluginContext } from '../kernel/types';
+import {
+  createAskPermissionService,
+  type AskPermissionServiceCreateOptions,
+} from '../permission/policy';
+import { createPermissionRuntimeService } from '../permission/runtime';
+import {
+  capekPermissionPolicyKey,
+  capekPermissionRuntimeKey,
+  capekRuntimeHostKey,
+} from './service-keys';
+
+/**
+ * C6 providers for the permission surface:
+ *
+ * - `capek.permission-policy` (REPLACEABLE advice/config): the permission
+ *   timeout translates into provider options here, at composition. The
+ *   generic ask timeout has no current configuration source and stays the
+ *   fixed 5-minute constant.
+ * - `capek.permission-runtime` (NON-REPLACEABLE lifecycle): request-id
+ *   routing, waiters, validation enforcement, raw-audit denial, and
+ *   canonical grant construction/persistence. A replacement policy can
+ *   change advice only; it can never approve malformed responses or create
+ *   grants outside the canonical allowed scopes.
+ */
+export function permissionPolicyPlugin(id: string): CapekPlugin<unknown> {
+  return {
+    id,
+    scope: 'agent',
+    provides: [capekPermissionPolicyKey, capekPermissionRuntimeKey],
+    requires: [capekRuntimeHostKey],
+    setup(context: PluginContext) {
+      const host = context.require(capekRuntimeHostKey);
+      const createOptions: AskPermissionServiceCreateOptions = {
+        id,
+        options: {
+          askTimeoutMs: 5 * 60 * 1000,
+          permissionTimeoutMs: host.interaction.getPermissionTimeoutMs(),
+        },
+      };
+      const policy = createAskPermissionService(createOptions);
+      context.provide(capekPermissionPolicyKey, policy);
+      context.provide(
+        capekPermissionRuntimeKey,
+        createPermissionRuntimeService({ id: `${id}.runtime`, provider: policy }),
+      );
+    },
+  };
+}

package/src/plugins/retry-policy.ts

@@ -0,0 +1,28 @@
+import type { CapekPlugin, PluginContext } from '../kernel/types';
+import {
+  createRetryPolicy,
+  type RetryPolicy,
+} from '../retry/policy';
+import { capekRetryPolicyKey } from './service-keys';
+
+/**
+ * C6 provider for the agent-scoped retry policy contract
+ * (`capek.retry-policy`). Wraps the exact current behavior through
+ * `createRetryPolicy()`: classification, exponential jittered backoff with
+ * Retry-After as a minimum, circuit state owned by this policy instance, and
+ * the no-retry-after-tool-activity side-effect barrier. Every composed agent
+ * scope gets its own policy instance, so circuit state is isolated per
+ * agent; the facade's pre-C6 per-agent `withRetryCircuitState` wrap is
+ * replaced by this scope-owned provider.
+ */
+export function retryPolicyPlugin(id: string): CapekPlugin<unknown> {
+  return {
+    id,
+    scope: 'agent',
+    provides: [capekRetryPolicyKey],
+    setup(context: PluginContext) {
+      const policy: RetryPolicy = createRetryPolicy({ id });
+      context.provide(capekRetryPolicyKey, policy);
+    },
+  };
+}