# Workspace Scope in agent-core-v2: Project-Level Isolation and Lifecycle Management

> Explore Workspace Scope in agent-core-v2 for project-level isolation and lifecycle management. Understand its role in the four-tier hierarchy for enhanced state management.

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

---

**The Workspace Scope in agent-core-v2 provides a project-oriented sandbox that isolates services, manages their lifecycle, and maintains per-project state, sitting between the application-wide App scope and the per-session Session scope in the four-tier hierarchy.**

The `agent-core-v2` package in the MoonshotAI/kimi-code repository organizes runtime components through a sophisticated dependency injection system built around four hierarchical lifecycle scopes. The **Workspace Scope** serves as the critical middle layer that creates isolated environments for individual project folders, ensuring that state, tools, and configurations remain separated between concurrent coding sessions.

## The Four-Tier Scope Hierarchy

`agent-core-v2` structures its runtime through four distinct lifecycle layers defined in [`packages/agent-core-v2/src/app/lifecycleScope.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/app/lifecycleScope.ts): **App**, **Workspace**, **Session**, and **Agent**. 

The App scope represents the application-wide singleton container that lives for the entire process lifetime. The Workspace scope sits immediately below App, creating a dedicated container for each open project directory. Below Workspace sits the Session scope for individual user interactions, followed by the Agent scope for specific AI agent instances.

This hierarchy ensures that services registered at the Workspace level are shared across all sessions within that project but remain isolated from other workspaces.

## Core Responsibilities of the Workspace Scope

The Workspace Scope manages five critical aspects of project-level runtime behavior:

### Isolation Between Projects

Each workspace instantiates its own dedicated services including the state store, tool-policy manager, skill-catalog, and file-system wrappers. When you open `/my/project` and `/another/project` simultaneously, `agent-core-v2` creates separate child containers via `host.child(LifecycleScope.Workspace, …)` for each path.

This isolation prevents data leakage between unrelated codebases and enables safe multi-workspace concurrency. Services registered through `registerScopedService(LifecycleScope.Workspace, …)` exist only within their respective project boundaries.

### Lifecycle Management

The `WorkspaceLifecycleService` in [`packages/agent-core-v2/src/app/workspaceLifecycle/workspaceLifecycleService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/app/workspaceLifecycle/workspaceLifecycleService.ts) governs the creation and teardown of workspace containers. When a user closes a workspace folder, the service automatically disposes the scope, triggering deterministic cleanup of all registered scoped services.

This automatic disposal guarantees that file watchers, caches, and temporary resources are promptly freed without manual intervention, preventing resource leaks during long-running IDE sessions.

### State and Configuration

`WorkspaceStateService` (located in [`packages/agent-core-v2/src/workspace/state/workspaceStateService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/state/workspaceStateService.ts)) maintains mutable workspace state such as opened files, UI layout preferences, and project-specific settings. Complementing this, `WorkspaceToolPolicyService` from [`packages/agent-core-v2/src/workspace/workspaceToolPolicy/workspaceToolPolicyService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/workspaceToolPolicy/workspaceToolPolicyService.ts) defines security boundaries by governing which external tools the workspace may invoke.

Together, these services give each project its own configurable environment while respecting security and trust policies defined by the user.

### Skill and Plugin Management

The `WorkspaceSkillCatalogService` in [`packages/agent-core-v2/src/workspace/workspaceSkillCatalog/workspaceSkillCatalogService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/workspaceSkillCatalog/workspaceSkillCatalogService.ts) discovers, loads, and indexes skills belonging to the workspace. Supporting file-source services like `WorkspaceRootSkillSource` and `ExplicitFileSkillSource` scan the project directory for commands, snippets, and extensions defined in workspace-specific locations such as `.kimi` folders.

This architecture allows individual projects to expose custom functionality without affecting the global application behavior or other open workspaces.

### Contextual Information

`WorkspaceContext` (defined in [`packages/agent-core-v2/src/workspace/workspaceContext/workspaceContext.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/workspaceContext/workspaceContext.ts)) supplies essential metadata including the current working directory (`cwd`) to downstream services. This context enables path-aware operations such as relative imports, file-system access, and project-root resolution that remain correct regardless of which workspace is currently active.

## Implementing Workspace Scope in Practice

Components interact with the Workspace Scope through the dependency injection container (`IContainer`). When code requests a workspace-scoped service, the container resolves the interface from the active workspace's child container.

```typescript
import { LifecycleScope } from '#/app/lifecycleScope';
import { createRootContainer } from '#/app/container';

// The root container represents the App scope
const appContainer = createRootContainer();

// Open a workspace at "/my/project"
const workspace = appContainer.child(
  LifecycleScope.Workspace,
  'workspace-1',
  [
    // Provide the workspace's cwd via the context service
    stubPair(IWorkspaceContext, { cwd: '/my/project' })
  ]
);

// Resolve a workspace-scoped service
const skillCatalog = workspace.accessor.get(IWorkspaceSkillCatalog);
await skillCatalog.load();       // discovers skills under /my/project/.kimi

// Use the workspace state service
const wsState = workspace.accessor.get(IWorkspaceStateService);
wsState.set('lastOpenedFile', 'src/index.ts');

// Enforce a tool-policy (e.g. disallow network calls)
const toolPolicy = workspace.accessor.get(IWorkspaceToolPolicy);
toolPolicy.setPolicy({ network: false });

// Clean up when the workspace is closed
workspace.dispose();   // automatically disposes all registered scoped services

```

The `child()` method creates a new container hierarchy, while `stubPair()` provides the contextual bindings needed for the workspace to function. All services retrieved through `workspace.accessor.get()` are automatically scoped to that specific project instance.

## Key Source Files and Implementation Details

Understanding the Workspace Scope requires familiarity with these specific implementation files in the MoonshotAI/kimi-code repository:

- [`packages/agent-core-v2/src/app/lifecycleScope.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/app/lifecycleScope.ts) – Defines the `LifecycleScope` enum (App, Workspace, Session, Agent) that drives the hierarchical container creation
- [`packages/agent-core-v2/src/app/workspaceLifecycle/workspaceLifecycleService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/app/workspaceLifecycle/workspaceLifecycleService.ts) – Implements the lifecycle management for the Workspace scope, handling creation, disposal, and event broadcasting
- [`packages/agent-core-v2/src/workspace/workspaceContext/workspaceContext.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/workspaceContext/workspaceContext.ts) – Provides the workspace's context including current working directory and environment variables
- [`packages/agent-core-v2/src/workspace/state/workspaceStateService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/state/workspaceStateService.ts) – Stores mutable per-workspace state including settings and UI state
- [`packages/agent-core-v2/src/workspace/workspaceToolPolicy/workspaceToolPolicyService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/workspaceToolPolicy/workspaceToolPolicyService.ts) – Governs external tool permissions and sandboxing policies per workspace
- [`packages/agent-core-v2/src/workspace/workspaceSkillCatalog/workspaceSkillCatalogService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/workspaceSkillCatalog/workspaceSkillCatalogService.ts) – Discovers and indexes skills defined within the workspace directory

## Summary

- The **Workspace Scope** sits between the App and Session scopes in `agent-core-v2`'s four-tier hierarchy, providing project-level isolation.
- Each workspace maintains its own **child container** created via `host.child(LifecycleScope.Workspace, …)`, ensuring services remain isolated between projects.
- **Automatic lifecycle management** handles cleanup of file watchers, caches, and resources when workspaces close via the `WorkspaceLifecycleService`.
- **Project-specific state** is managed through `WorkspaceStateService` while security policies are enforced by `WorkspaceToolPolicyService`.
- **Skill discovery** happens through `WorkspaceSkillCatalogService`, allowing workspaces to define custom commands and extensions without global impact.

## Frequently Asked Questions

### What is the difference between Workspace scope and Session scope?

**Workspace scope persists for the duration of an open project folder**, managing project-level services like file watchers and skill catalogs, while **Session scope is temporary** and tied to individual user interaction sequences. Multiple sessions can exist within a single workspace, sharing the workspace's services but maintaining their own session-specific state like conversation history.

### How does the Workspace scope handle cleanup when a project is closed?

When a workspace closes, the `WorkspaceLifecycleService` calls `dispose()` on the workspace container, which automatically triggers teardown of all services registered via `registerScopedService(LifecycleScope.Workspace, …)`. This deterministic disposal pattern ensures file system watchers, network connections, and cached indexes are released immediately, preventing resource leaks in long-running applications.

### Can multiple workspaces run concurrently in agent-core-v2?

**Yes**, `agent-core-v2` supports multi-workspace concurrency by creating separate child containers for each open project directory. Each workspace maintains isolated instances of `WorkspaceStateService`, `WorkspaceSkillCatalogService`, and other scoped services. The dependency injection container routes service requests to the appropriate workspace instance based on the active context, preventing data leakage between unrelated projects.

### How are workspace-specific skills discovered and loaded?

The `WorkspaceSkillCatalogService` coordinates with `WorkspaceRootSkillSource` and `ExplicitFileSkillSource` to scan the workspace directory—typically looking for `.kimi` folders or configured skill paths. These services index custom commands, snippets, and extensions defined within the project, making them available to agents and tools while keeping them isolated from other workspaces. This discovery happens automatically when the workspace scope initializes via `skillCatalog.load()`.