Workspace Tier Services in agent-core-v2: Complete Guide to Workspace-Scoped Dependencies

The agent-core-v2 architecture manages 15+ singleton services at the Workspace tier—including trust evaluation, tool policy enforcement, skill catalog aggregation, MCP process management, and file system abstraction—all instantiated per workspace via LifecycleScope.Workspace and disposed when the workspace terminates.

In the MoonshotAI/kimi-code repository, the agent-core-v2 package implements a four-level hierarchical dependency injection system: App → Workspace → Session → Agent. Services registered at the Workspace tier are created once when a workspace initializes and persist for the workspace's entire lifetime, providing isolated security contexts, skill discovery, and file access capabilities scoped to that specific workspace directory.

Understanding the Workspace Lifecycle Scope

agent-core-v2 defines lifecycle scopes in packages/agent-core-v2/src/app/scopes.ts to manage service instantiation boundaries. When you create a workspace using host.child(LifecycleScope.Workspace, ...), the system instantiates a new dependency injection container that owns a unique set of services. These services live exactly as long as the workspace exists and are destroyed when the workspace is torn down, ensuring clean resource management and isolation between different workspace contexts.

Workspace-tier services reside in packages/agent-core-v2/src/workspace/ and its subdirectories. They collectively form a self-contained environment that handles everything from Git operations to agent profile loading.

Core Workspace Services by Category

Trust and Policy Enforcement

WorkspaceTrustService (packages/agent-core-v2/src/workspace/workspaceTrust/workspaceTrustService.ts) persists and evaluates the trust level of a workspace (trusted, limited, or untrusted). WorkspaceToolPolicyService (packages/agent-core-v2/src/workspace/workspaceToolPolicy/workspaceToolPolicyService.ts) controls which external tools the workspace may invoke, enforcing security boundaries at the workspace level.

Skill Discovery and Management

WorkspaceSkillCatalogService (packages/agent-core-v2/src/workspace/workspaceSkillCatalog/workspaceSkillCatalogService.ts) aggregates all skill sources for a workspace and resolves skill lookups. It consumes four distinct skill sources:

• ExplicitFileSkillSource (packages/agent-core-v2/src/workspace/workspaceSkillCatalog/explicitFileSkillSource.ts) – Loads skills from explicit JSON files.
• ExtraFileSkillSource (packages/agent-core-v2/src/workspace/workspaceSkillCatalog/extraFileSkillSource.ts) – Loads optional or extra skill files.
• WorkspaceRootSkillSource (packages/agent-core-v2/src/workspace/workspaceSkillCatalog/rootFileSkillSource.ts) – Scans the workspace root for skill definitions.
• PluginSkillSource (packages/agent-core-v2/src/workspace/workspaceSkillCatalog/pluginSkillSource.ts) – Loads skills contributed by plugins.

Process Execution and MCP Configuration

WorkspaceProcessRunnerService (packages/agent-core-v2/src/workspace/workspaceProcessRunner/workspaceProcessRunnerService.ts) executes subprocesses such as LLM calls and tooling commands within the workspace context. For Manifest-Controlled-Process (MCP) support, WorkspaceMcpConfigService (packages/agent-core-v2/src/workspace/workspaceMcp/workspaceMcpConfigService.ts) reads MCP configuration files, while WorkspaceMcpService (packages/agent-core-v2/src/workspace/workspaceMcp/workspaceMcpService.ts) manages MCP-driven process lifecycles (starting, stopping, and reloading).

File System and Version Control

The file system services provide sandboxed access to workspace files:

• FsService (packages/agent-core-v2/src/workspace/workspaceFs/fsService.ts) – General file-system utilities for reading, writing, and searching within the workspace.
• FsWatchService (packages/agent-core-v2/src/workspace/workspaceFs/fsWatchService.ts) – Watches the filesystem for changes inside the workspace.
• WorkspaceGitService (packages/agent-core-v2/src/workspace/workspaceGit/workspaceGitService.ts) – Wraps Git operations (status, diff, commits) scoped to the workspace directory.
• WorkspaceDirsService (packages/agent-core-v2/src/workspace/workspaceDirs/workspaceDirsService.ts) – Tracks special directories such as src, dist, and .git within the workspace.

State Persistence and Customization

WorkspaceStateService (packages/agent-core-v2/src/workspace/state/workspaceStateService.ts) holds mutable state—including cached skill data and trust levels—for the workspace's lifetime. WorkspaceInstructionsService (packages/agent-core-v2/src/workspace/workspaceInstructions/workspaceInstructionsService.ts) provides the instructions block that customizes agent behavior for the specific workspace.

Agent Profile Loading

WorkspaceAgentProfileLoaderService (packages/agent-core-v2/src/workspace/workspaceAgentProfileLoader/workspaceAgentProfileLoaderService.ts) loads agent profiles belonging to a workspace. It delegates to four concrete loaders:

• UserAgentProfileLoaderService (packages/agent-core-v2/src/workspace/workspaceAgentProfileLoader/userAgentProfileLoaderService.ts) – Loads user-defined profiles from .kimi/agents/*.json.
• PluginAgentProfileLoaderService (packages/agent-core-v2/src/workspace/workspaceAgentProfileLoader/pluginAgentProfileLoaderService.ts) – Loads profiles contributed by plugins.
• ExtraAgentProfileLoaderService (packages/agent-core-v2/src/workspace/workspaceAgentProfileLoader/extraAgentProfileLoaderService.ts) – Loads optional extra profile files.
• ExplicitAgentProfileLoaderService (packages/agent-core-v2/src/workspace/workspaceAgentProfileLoader/explicitAgentProfileLoaderService.ts) – Loads explicitly declared profile files.

Accessing Workspace-Tier Services in Code

Services are retrieved through the workspace's accessor after creation via host.child(LifecycleScope.Workspace, ...).

Accessing Trust and Skill Catalog Services

import { host, LifecycleScope } from '#/app/host';
import { IWorkspaceTrust } from '#/workspace/workspaceTrust/workspaceTrust';
import { IWorkspaceSkillCatalog } from '#/workspace/workspaceSkillCatalog/workspaceSkillCatalog';

// Create a new workspace instance (second argument is an arbitrary ID)
const ws = host.child(LifecycleScope.Workspace, 'my-ws', []);

// Retrieve the trust service (workspace-scoped)
const trustService = ws.accessor.get(IWorkspaceTrust);
await trustService.setTrusted();   // marks the workspace as trusted

// Retrieve the skill catalog (also workspace-scoped)
const catalog = ws.accessor.get(IWorkspaceSkillCatalog);
const skill = await catalog.get('my.custom.skill');

Source: This pattern is demonstrated in the test suite at packages/agent-core-v2/test/workspace/workspaceResources.test.ts.

Performing File System Operations

import { IWorkspaceFs } from '#/workspace/workspaceFs/fs';

const fs = ws.accessor.get(IWorkspaceFs);

// Search for all `.md` files in the workspace
const results = await fs.search('*.md');

// Write a temporary file
await fs.writeFile('tmp/generated.txt', 'Hello, workspace!');

Source: The FsService implementation lives in packages/agent-core-v2/src/workspace/workspaceFs/fsService.ts.

Loading Agent Profiles

import { IWorkspaceAgentProfileLoader } from '#/workspace/workspaceAgentProfileLoader/workspaceAgentProfileLoader';

const profileLoader = ws.accessor.get(IWorkspaceAgentProfileLoader);
const profiles = await profileLoader.loadAll(); // returns all agents defined for the workspace

Source: The loader is defined in packages/agent-core-v2/src/workspace/workspaceAgentProfileLoader/workspaceAgentProfileLoaderService.ts.

Summary

• Workspace-tier services in agent-core-v2 are scoped to the LifecycleScope.Workspace container, living exactly as long as the workspace exists.
• The architecture includes security services (trust, tool policy), skill management (catalog plus four skill sources), execution services (process runner, MCP), file system abstraction (FS, Git, watching), and configuration loading (instructions, agent profiles).
• Services are accessed via ws.accessor.get(ServiceInterface) after creating the workspace with host.child(LifecycleScope.Workspace, id, []).
• All implementations reside in packages/agent-core-v2/src/workspace/ with concrete service implementations following the *Service.ts naming convention.

Frequently Asked Questions

What distinguishes Workspace tier services from Session or Agent tier services?

Workspace tier services persist for the entire lifetime of a workspace instance, whereas Session tier services are created per user session and Agent tier services are instantiated per active agent. According to packages/agent-core-v2/src/app/scopes.ts, the hierarchy flows App → Workspace → Session → Agent, meaning Workspace services are shared across all sessions and agents within that workspace but isolated from other workspaces.

How does WorkspaceSkillCatalogService resolve available skills?

The service aggregates skills from four distinct sources: explicit file sources, extra file sources, workspace root scanning, and plugin contributions. When catalog.get('skill.id') is called, the WorkspaceSkillCatalogService queries these sources in order to resolve the skill definition, as implemented in packages/agent-core-v2/src/workspace/workspaceSkillCatalog/workspaceSkillCatalogService.ts.

Which services handle version control operations at the Workspace tier?

WorkspaceGitService wraps all Git operations including status checks, diff generation, and commit management, scoped specifically to the workspace directory. It is complemented by WorkspaceDirsService for tracking special repository directories and FsWatchService for monitoring file changes that might affect version control state.

How are agent profiles loaded differently from skills?

While skills are loaded via WorkspaceSkillCatalogService, agent profiles use WorkspaceAgentProfileLoaderService, which delegates to four specialized loaders: user-defined profiles (from .kimi/agents/), plugin-contributed profiles, extra files, and explicit declarations. This separation allows different resolution strategies for agent configurations versus executable skills, as defined in packages/agent-core-v2/src/workspace/workspaceAgentProfileLoader/.

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