# Differences Between agent-core and agent-core-v2 in Kimi-Code: Architecture, DI, and Scope Hierarchy

> Explore the differences between agent-core and agent-core-v2 in Kimi-Code. Understand the shift to a four-tier lifecycle scope system and full dependency injection in v2, contrasting with v1's direct instantiation.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: deep-dive
- Published: 2026-08-14

---

**`agent-core-v2` replaces the monolithic v1 engine with a four-tier lifecycle scope system (App → Workspace → Session → Agent) and full dependency injection, while `agent-core` relies on direct instantiation and minimal DI.**

The `agent-core` and `agent-core-v2` packages in the MoonshotAI/kimi-code repository represent two distinct generations of the Kimi agent engine. While both provide the fundamental capabilities for running AI agents, sessions, and tool execution, they differ dramatically in architectural philosophy, dependency management, and extensibility.

## Architecture Overview

### agent-core v1 (Monolithic Design)

The original `agent-core` package provides a straightforward, mostly static implementation where agents are created directly via the exported `Agent` class. According to the hard rules defined in [`packages/agent-core/AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/AGENTS.md), the v1 engine does not depend on a higher-level session lifecycle—agents optionally receive a `sessionId` but operate independently of structured scope management.

All logic lives under `packages/agent-core/src/`, with directories like `tools/`, `mcp/`, and `profile/` coexisting without explicit architectural boundaries. The package exports its public API from [`packages/agent-core/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/index.ts) and serves the legacy CLI (`apps/kimi-code`).

### agent-core-v2 (Scoped DI Architecture)

The successor introduces a **four-tier `LifecycleScope` hierarchy** defined in [`packages/agent-core-v2/src/app/scopes.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/app/scopes.ts):

1. **App Scope** – Top-level container owning global services
2. **Workspace Scope** – Isolated file-system, Git, and policy contexts  
3. **Session Scope** – Conversation state and agent factories
4. **Agent Scope** – Individual agent instances with resolved dependencies

Each tier owns its lifecycle (creation, disposal, state persistence) and participates in a full dependency injection container (`IServiceProvider`, `IFlagService`). The package exports from [`packages/agent-core-v2/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/index.ts) and powers the modern Kap-Server (`packages/kap-server`) and the `@moonshot-ai/klient` SDK.

## Key Architectural Differences

### Lifecycle Management

**agent-core** uses direct instantiation without enforced parent-child relationships:

```typescript
import { Agent } from '@moonshot-ai/agent-core';

// Simple instantiation – optional sessionId hint only
const agent = new Agent({ sessionId: 'my-session' });
await agent.runPrompt('Analyze this codebase');

```

**agent-core-v2** requires explicit scope resolution through the DI container:

```typescript
import { createAppScope } from '@moonshot-ai/agent-core-v2/app';
import { Agent } from '@moonshot-ai/agent-core-v2/agent';

// Build the top-level App scope
const app = await createAppScope();

// Resolve nested scopes sequentially
const session = await app.sessionService.createSession('my-session');
const agent = await session.agentFactory.createAgent();
await agent.runPrompt('Analyze this codebase');

```

### Dependency Injection Design

The v1 engine uses **minimal DI**—most components import dependencies directly through ES6 modules. This creates tight coupling between tools, profiles, and session handlers.

The v2 engine implements a **service graph pattern** where services register in the container and resolve on demand. The DI utilities in [`packages/agent-core-v2/src/app/web/web-fetch-service.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/app/web/web-fetch-service.ts) demonstrate how `IServiceProvider` manages singleton and scoped lifetimes. Services like `workspaceTrustService` and `workspaceToolPolicyService` are injected rather than imported, enabling test mocking and runtime reconfiguration.

### Workspace Abstraction Layer

`agent-core` lacks a dedicated workspace layer—agents operate directly on a session or the global process context.

`agent-core-v2` introduces a rich **Workspace layer** that isolates per-directory concerns through specialized services:

- **[`workspaceTrustService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/workspaceTrustService.ts)** – Trust-model handling for tool execution permissions
- **[`workspaceToolPolicyService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/workspaceToolPolicyService.ts)** – Per-workspace tool-access policies  
- **[`workspaceSkillCatalogService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/workspaceSkillCatalogService.ts)** – Skill discovery and catalog management
- **[`workspaceMcpService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/workspaceMcpService.ts)** – Multi-Channel Protocol handling scoped to the workspace directory

These services enforce security boundaries and configuration inheritance from the App scope down to individual agents.

### Feature Seams vs Monolithic Logic

In `agent-core`, functionality clusters under `src/` directories without explicit boundaries between core services and experimental capabilities.

`agent-core-v2` introduces a **Feature seam** (`src/features/`) that groups related capabilities (plan execution, swarm coordination, debug events) into composable units. Features integrate with the **Flag system** via `registerFlagDefinition` (documented in [`packages/agent-core-v2/docs/flag.md`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/docs/flag.md)), allowing runtime enablement without code changes:

```typescript
import { FlagService } from '@moonshot-ai/agent-core-v2/flags';

if (FlagService.enabled('distributed-swarm')) {
  // Enable swarm coordination feature
}

```

This contrasts with v1's simple `flags.enabled('name')` lookup in [`packages/agent-core/src/flags/registry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/flags/registry.ts).

### Testing Architecture

Tests in `agent-core` live under `packages/agent-core/test/` and focus on individual tool modules in isolation.

The v2 test suite in `packages/agent-core-v2/test/workspace/` validates scope hierarchy interactions, such as [`sessionLifecycle.test.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/sessionLifecycle.test.ts), which verifies that disposal of a Workspace scope properly cascades to child Sessions and Agents.

## Code Implementation Comparison

### Creating an Agent

The v1 approach emphasizes immediate construction:

```typescript
import { Agent } from '@moonshot-ai/agent-core';

const agent = new Agent({ sessionId: 'dev-session' });
await agent.runPrompt('Refactor this function');

```

The v2 approach requires container resolution and factory patterns:

```typescript
import { createAppScope } from '@moonshot-ai/agent-core-v2/app';

const app = await createAppScope();
const workspace = await app.workspaceService.open('/project/path');
const session = await workspace.createSession('dev-session');
const agent = await session.agentFactory.createAgent();
await agent.runPrompt('Refactor this function');

```

### Accessing Workspace Services

V2 exposes workspace-specific capabilities through injected services:

```typescript
// Inside a Workspace scope
const ws = await session.workspaceService.getWorkspace('my-project');

// Check trust model
const isTrusted = await ws.trustService.isToolTrusted('shell-execute');

// Verify policy
const canExecute = await ws.toolPolicyService.checkPolicy('shell-execute', {
  command: 'rm -rf /'
});

```

## Migration and Compatibility

`agent-core` remains in maintenance mode for the legacy CLI but receives no new features. `agent-core-v2` serves as the target for all new development, including distributed agent support and per-workspace policy enforcement.

Migration requires restructuring initialization code from direct `Agent` construction to scope-based resolution. The v2 SDK (`@moonshot-ai/klient`) abstracts much of this complexity for client applications, while server implementations (`packages/kap-server`) interact directly with the scope hierarchy.

## Summary

- **agent-core** provides a monolithic, directly instantiated agent engine with minimal DI and no workspace abstraction
- **agent-core-v2** implements a four-tier lifecycle scope (App → Workspace → Session → Agent) with full dependency injection
- V2 introduces dedicated workspace services (`workspaceTrustService`, `workspaceToolPolicyService`) for security isolation
- The Feature seam system in V2 enables runtime capability toggling via `registerFlagDefinition`
- V1 exports from [`packages/agent-core/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/index.ts) for legacy CLI; V2 exports from [`packages/agent-core-v2/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/index.ts) for modern Kap-Server
- V2 tests validate scope lifecycle interactions, while V1 tests focus on isolated tool logic

## Frequently Asked Questions

### What triggers the scope disposal hierarchy in agent-core-v2?

When a parent scope disposes, it automatically triggers disposal of all child scopes in reverse creation order. For example, disposing a Workspace scope automatically cleans up active Sessions and their Agents, ensuring proper resource cleanup and state persistence as implemented in [`packages/agent-core-v2/src/app/scopes.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/app/scopes.ts).

### Can I mix agent-core and agent-core-v2 in the same application?

While both packages can technically coexist in a Node.js process, they do not share state or service instances. The v1 `Agent` class cannot resolve services from the v2 DI container, and v2 scopes cannot reference v1 global instances. Migration requires porting initialization logic from direct instantiation to scope-based resolution.

### How does the workspace trust model differ from v1 security?

In `agent-core`, tool permissions typically rely on global configuration or session-level flags. `agent-core-v2` implements [`workspaceTrustService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/workspaceTrustService.ts) to evaluate tool trust based on workspace-directory reputation, user verification status, and policy inheritance, allowing different safety rules for `/trusted/project` versus `/tmp/untrusted` workspaces.

### Where are experimental features configured in v2?

Experimental features register through the `registerFlagDefinition` API documented in [`packages/agent-core-v2/docs/flag.md`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/docs/flag.md). Unlike v1's central registry in [`packages/agent-core/src/flags/registry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/flags/registry.ts), v2 allows individual features to declare their flags locally within the `src/features/` directory, then checks runtime state via `FlagService.enabled('feature-name')`.