# Understanding the Agent Scope in agent-core-v2: Isolation and Lifecycle Management in MoonshotAI

> Discover the Agent Scope in agent-core-v2. Learn how it isolates per-agent services, tools, and telemetry for LLM processes, ensuring secure and efficient operations within MoonshotAI.

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

---

**The Agent Scope in agent-core-v2 represents the fourth and innermost tier of MoonshotAI's dependency injection kernel, isolating per-agent services, tools, and telemetry state for individual LLM processes while maintaining hierarchical access to parent container resources.**

The `agent-core-v2` package within the MoonshotAI/kimi-code repository implements a sophisticated four-level DI (Dependency Injection) topology. The Agent Scope sits at the innermost level, encapsulating everything that must live for the duration of a single logical "agent"—from model bindings and system prompts to active tool registries and profile configurations.

## The Four-Tier DI Hierarchy

MoonshotAI's architecture organizes dependency containers into a strict parent-child hierarchy. The Agent Scope is declared 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) and registered with the DI kernel via `setScopeTopology` to establish this inheritance chain:

| Tier | Parent Relationship | Typical Lifetime | Key Responsibilities |
|------|---------------------|----------------|---------------------|
| **App** | Root | Process lifetime | Global services, feature registry |
| **Workspace** | `App` → `Workspace` | Workspace on disk | Workspace-wide state, tool-policy |
| **Session** | `Workspace` → `Session` | Terminal/REPL session | Session-level state, model binding |
| **Agent** | `Session` → `Agent` | Single LLM process | **Per-agent services, tool registry, profile, telemetry, state** |

When the kernel creates isolated child containers, it uses `host.child(LifecycleScope.Agent, …)` to instantiate this innermost tier, ensuring each agent receives a fresh service container.

## Core Responsibilities of the Agent Scope

### Isolation of Per-Agent Services

Each agent receives independent instances of services registered with `LifecycleScope.Agent`. This prevents state leakage between concurrent agents. In [`packages/agent-core-v2/src/agent/profile/profileService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/agent/profile/profileService.ts), the service registration explicitly targets this scope:

```typescript
registerScopedService(
  LifecycleScope.Agent,
  IAgentProfileService,
  AgentProfileService,
  ScopeActivation.OnScopeCreated,
  'profile',
);

```

As noted in the extensive comment block at the top of [`profileService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/profileService.ts), agent profiles are "Bound at Agent scope," meaning model configurations and system prompts remain frozen for the agent's entire lifetime.

### Feature Contribution Venue

Features can contribute services, tools, or recipes specifically to the Agent scope. The test suite in [`packages/agent-core-v2/test/features/feature.test.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/test/features/feature.test.ts) (lines 96-100) demonstrates this isolation by registering an `IGreeter` service and verifying that separate agents receive distinct instances:

```typescript
this.contributeAgentService(IGreeter, GreeterService);
// Later verification:
expect(agentOne.accessor.get(IGreeter)).not.toBe(agentTwo.accessor.get(IGreeter));

```

### Lifetime-Bounded Resources

Resources such as active tool sets, telemetry contexts (`IAgentTelemetryContextService`), and state overlays (`IAgentStateService`) are stored at the Agent level. When an agent shuts down, these resources are automatically released, preventing memory leaks across sessions.

### Hierarchical Lookup with Override Capability

If a requested service is not found in the Agent scope, the DI kernel walks up the hierarchy (Session → Workspace → App). This allows agents to inherit higher-level defaults while maintaining the ability to override them with agent-specific implementations.

## Working with the Agent Scope: Practical Examples

### Registering Agent-Scoped Services

Services must be explicitly registered to the Agent scope to receive per-agent instantiation:

```typescript
// From packages/agent-core-v2/src/app/scopes.ts
enum LifecycleScope {
  App = 'app',
  Workspace = 'workspace',
  Session = 'session',
  Agent = 'agent',
}

// Custom service registration
registerScopedService(
  LifecycleScope.Agent,
  ICustomAgentLogger,
  CustomAgentLogger,
  ScopeActivation.OnScopeCreated,
  'agentLogger',
);

```

### Creating Agent Containers

Runtime instantiation follows the hierarchical pattern:

```typescript
const host = createScopedTestHost();
const session = host.child(LifecycleScope.Session, 's1');
const agent = session.createChild(LifecycleScope.Agent, 'agent-1');

// Resolve per-agent profile service
const profileService = agent.accessor.get(IAgentProfileService);
await profileService.bind({ profile: 'default', model: 'gpt-4' });

```

### Contributing Tools to Individual Agents

Features use the Feature API to inject capabilities specific to the Agent scope:

```typescript
class MyFeature extends Feature {
  static override readonly name = 'my-feature';

  constructor() {
    super();
    // Tool available only to agents created after this feature loads
    this.contributeTool(ITestTool, TestTool, { name: 'TestTool' });
  }
}

```

### Accessing Per-Agent State

Retrieve frozen state values such as active tool configurations:

```typescript
const activeTools = agent.accessor
  .get(IAgentStateService)
  .get(profileActiveToolNamesOverlayKey);
  
console.log('Active tools for this agent:', activeTools);

```

## Key Implementation Files

- **[`packages/agent-core-v2/src/app/scopes.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/app/scopes.ts)** – Declares the `LifecycleScope` enum and registers the topology with `setScopeTopology` to establish parent-child relationships.
- **[`packages/agent-core-v2/src/agent/profile/profileService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/agent/profile/profileService.ts)** – Implements `AgentProfileService`; lines 51-57 contain the scope registration that binds profiles at the Agent level.
- **[`packages/agent-core-v2/src/features/feature.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/features/feature.ts)** – Core API (lines 84-92) exposing `contributeAgentService()` and `contributeTool()` for scope-specific feature injection.
- **[`packages/agent-core-v2/test/features/feature.test.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/test/features/feature.test.ts)** – Demonstrates isolation guarantees between agents (lines 90-124), verifying that scoped services are not shared across agent instances.
- **[`packages/agent-core-v2/test/_base/di/scoped-test-container.test.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/test/_base/di/scoped-test-container.test.ts)** – Validates container creation and disposal behavior for Agent-scoped resources.

## Summary

- The Agent Scope is the **fourth and innermost tier** of the DI hierarchy (App → Workspace → Session → Agent), declared 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).
- It guarantees **strict isolation** of services like `IAgentProfileService` and `IAgentStateService`, ensuring each LLM process receives independent instances.
- Features contribute tools and services specifically to this scope using `contributeAgentService()` and `contributeTool()`, with automatic instance separation between agents.
- Resources bound at this scope are **automatically disposed** when the agent shuts down, preventing cross-session memory leaks.
- The scope supports **hierarchical resolution**, allowing agents to access parent scope resources while maintaining override capabilities for agent-specific configurations.

## Frequently Asked Questions

### What distinguishes the Agent Scope from the Session Scope in agent-core-v2?

The Session Scope manages terminal or REPL session-level state and model bindings, while the Agent Scope sits one level deeper as the fourth tier, isolating resources for a single LLM process. According to the source code 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), the Session acts as the parent container, meaning multiple Agent scopes can exist within a single session, each with independent service instances.

### How does the Agent Scope handle service disposal?

When an agent is disposed, the DI kernel automatically disposes all services registered in the Agent scope, ensuring deterministic cleanup of resources like telemetry contexts and active tool registries. This prevents memory leaks and state pollution across different agent instances, as demonstrated in the scoped container tests at [`packages/agent-core-v2/test/_base/di/scoped-test-container.test.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/test/_base/di/scoped-test-container.test.ts).

### Can services registered in parent scopes be accessed from within an Agent?

Yes. If a service is not found in the Agent scope, the DI kernel performs hierarchical lookup walking up through Session, Workspace, and App scopes. This allows agents to inherit global defaults while maintaining the ability to override them with agent-specific implementations, providing flexibility while preserving isolation boundaries.

### How do features contribute tools exclusively to individual agents?

Features use the `contributeAgentService()` or `contributeTool()` methods available in the Feature API, specifying that the contribution targets the Agent scope. As shown in [`packages/agent-core-v2/test/features/feature.test.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/test/features/feature.test.ts), this ensures that each agent receives its own instance of the service, such as the `IGreeter` example where `agentOne` and `agentTwo` receive distinct `GreeterService` instances.