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

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

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 – Defines the LifecycleScope enum (App, Workspace, Session, Agent) that drives the hierarchical container creation
• 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 – Provides the workspace's context including current working directory and environment variables
• 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 – Governs external tool permissions and sandboxing policies per workspace
• 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().

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