# How Session Scope Provides Isolation for Conversations in agent-core-v2

> Discover how agent-core-v2 uses Session Scope to isolate conversations. Learn how child containers ensure separate service instances and state for each interaction in MoonshotAI/kimi-code.

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

---

**In MoonshotAI/kimi-code, the `agent-core-v2` architecture isolates each conversation by running it inside a dedicated Session Scope—a child dependency-injection container that maintains separate service instances and state from all other sessions.**

The `agent-core-v2` package manages AI conversations through a sophisticated scoping system designed to prevent cross-contamination of memory, tool state, and telemetry data. When multiple conversations run concurrently or sequentially, the framework must guarantee that resources from one session cannot leak into another. The Session Scope pattern achieves this by creating hierarchical dependency-injection containers that strictly compartmentalize each conversation's resources.

## Core Isolation Mechanisms in Session Scope

### Creating a Child DI Container

When a new session starts, `SessionLifecycleService.create` invokes `createScopedChildHandle` with the `LifecycleScope.Session` kind. According to the source code in [`packages/agent-core-v2/src/workspace/sessionLifecycle/sessionLifecycleService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/sessionLifecycle/sessionLifecycleService.ts) (lines 51-57), this instantiates a fresh `InstantiationService` child container that exists solely for that conversation, completely separate from the workspace and application containers.

### Seeding Session-Specific Services

The framework supplies initial *seeds* to the child container during creation. As implemented in [`sessionLifecycleService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/sessionLifecycleService.ts) (lines 108-119), these seeds include `ISessionContext`, telemetry providers, agent-profile catalogs, and process runners. These objects become singletons within the session scope, ensuring they remain invisible to other sessions while being shared within their own conversation context.

### Isolated Service Accessors

The returned `ISessionScopeHandle` contains an `accessor` property—typed as `ServicesAccessor`—that resolves services exclusively from the child container. Code in [`packages/agent-core-v2/src/_base/di/scope.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/_base/di/scope.ts) (lines 91-96) demonstrates that this accessor restricts dependency resolution to the session's own container, preventing accidental cross-session service access.

### Lifetime Management and Disposal

When conversations end, `SessionLifecycleService.close` triggers `handle.dispose()`. The implementation in [`sessionLifecycleService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/sessionLifecycleService.ts) (lines 30-38) demonstrates that disposing the child `InstantiationService` destroys all services created within that scope, frees memory, and eliminates lingering references that could cause leaks between sessions.

### Hierarchical Scope Ordering

Session scopes exist in a strict hierarchy enforced by `Scope.createChild` in [`scope.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/scope.ts) (lines 12-23). Session scopes sit **below** the workspace scope, ensuring sessions inherit only read-only configuration from ancestor containers while remaining unable to access or modify sibling workspace or application services.

### Conversation State Isolation

All per-conversation data—including dialog history, tool calls, agent lifecycles, and telemetry tags—lives within session-scoped services like `ISessionMetadata` and `IAgentLifecycleService`. As shown in [`sessionLifecycleService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/sessionLifecycleService.ts) (lines 36-44), each session's unique handle ensures two concurrent conversations never share the same state objects, even when running in parallel.

## Why Session Scope Guarantees Isolation

The architecture ensures complete conversation isolation through four key design principles:

- **Separate DI Containers**: Each session receives its own `InstantiationService` child; service instances are not singletons across sessions.
- **Unique Session IDs**: The `ISessionScopeHandle.id` serves as the session identifier, used by every scoped service to index its data.
- **Explicit Disposal**: The `dispose` method removes the child scope from its parent and tears down its ledger, preventing memory leakage.
- **Controlled Inheritance**: Session scopes inherit only read-only configuration from workspace and app scopes; they cannot mutate parent services.

## Practical Implementation Examples

### Creating an Isolated Session

```typescript
import { SessionLifecycleService } from '#/workspace/sessionLifecycle/sessionLifecycleService';
import { CreateSessionOptions } from '#/workspace/sessionLifecycle/types';

async function startConversation(workspaceContext, opts: CreateSessionOptions) {
  const sessionService = workspaceContext.sessionLifecycle;
  const sessionHandle = await sessionService.create(opts);
  return sessionHandle;
}

```

The returned `sessionHandle` implements `ISessionScopeHandle` and provides an `accessor` that resolves services only for that specific conversation.

### Accessing Scoped Services

```typescript
const mainAgent = await sessionHandle.accessor
  .get(IAgentLifecycleService)
  .create({ agentId: 'main', binding: opts.mainAgentBinding });

await mainAgent.sendMessage('Hello, world!');

```

All calls to `IAgentLifecycleService` resolve inside the session's DI container, keeping the agent's state private to that session.

### Forking Sessions

```typescript
const forkedHandle = await sessionService.fork({
  parentSessionId: sessionHandle.id,
  workDir: '/tmp/fork',
});

```

The fork operation creates a brand-new `ISessionScopeHandle` with its own child container, inheriting only read-only values from the parent session.

### Cleaning Up Resources

```typescript
await sessionService.close(sessionHandle.id);

```

This invocation runs `handle.dispose()`, destroying the entire child container and releasing all isolated resources.

## Key Source Files

The Session Scope isolation mechanism is implemented across these critical files:

- **[`packages/agent-core-v2/src/_base/di/scope.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/_base/di/scope.ts)**: Defines `IScopeHandle`, scoped service registration, and `createScopedChildHandle` that constructs Session Scopes.
- **[`packages/agent-core-v2/src/workspace/sessionLifecycle/sessionLifecycleService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/sessionLifecycle/sessionLifecycleService.ts)**: Orchestrates session creation, materialization, and disposal; uses `createScopedChildHandle` to produce isolated handles.
- **[`packages/agent-core-v2/src/workspace/sessionLifecycle/sessionLifecycle.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/sessionLifecycle/sessionLifecycle.ts)**: Exposes the public session-lifecycle API including `create`, `resume`, `fork`, and `close` methods.
- **[`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 scope topology (`app → workspace → session → agent`) that enforces hierarchical isolation.

## Summary

- **Session Scope** creates a dedicated child DI container for each conversation in `agent-core-v2`.
- **Isolation** is enforced through separate `InstantiationService` instances, unique session IDs, and hierarchical scope ordering.
- **Seeding** ensures each session receives its own instances of `ISessionContext`, telemetry, and agent catalogs.
- **Disposal** guarantees cleanup via `SessionLifecycleService.close`, which tears down the child container and frees all associated resources.
- **Forking** creates entirely new scopes while maintaining read-only inheritance from parent sessions.

## Frequently Asked Questions

### What is a Session Scope in agent-core-v2?

A Session Scope is a dedicated dependency-injection child container created for each conversation. It encapsulates all services, state, and resources—such as dialog history and tool configurations—ensuring complete isolation from other concurrent or sequential sessions.

### How does Session Scope prevent memory leaks between conversations?

When `SessionLifecycleService.close` is called, it invokes `handle.dispose()` on the `ISessionScopeHandle`. This disposes the child `InstantiationService`, which tears down all service instances and removes the scope from the parent container's ledger, ensuring no references persist after the conversation ends.

### Can sessions access each other's state?

No. Each session operates with its own `ServicesAccessor` that resolves instances exclusively from its child container. Because services like `ISessionMetadata` and `IAgentLifecycleService` are scoped to the session level, two conversations cannot share state objects or interfere with each other's memory.

### What happens when a session is forked?

Forking creates a new `ISessionScopeHandle` with its own isolated DI container via `sessionService.fork`. The forked session inherits read-only configuration from its parent but receives fresh instances of all scoped services, ensuring the forked conversation operates independently while maintaining the desired parent-child relationship.