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

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, 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 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:

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 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:

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:

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 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 – Trust-model handling for tool execution permissions
• workspaceToolPolicyService.ts – Per-workspace tool-access policies
• workspaceSkillCatalogService.ts – Skill discovery and catalog management
• 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), allowing runtime enablement without code changes:

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.

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, 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:

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:

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:

// 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 for legacy CLI; V2 exports from 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.

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 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. Unlike v1's central registry in 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').

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}