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

> Discover Workspace tier services in agent-core-v2. Learn about 15+ singleton services like trust evaluation and tool policy enforcement managed per workspace for efficient dependency handling.

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

---

**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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/workspaceMcp/workspaceMcpConfigService.ts)) reads MCP configuration files, while **WorkspaceMcpService** ([`packages/agent-core-v2/src/workspace/workspaceMcp/workspaceMcpService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/workspaceAgentProfileLoader/pluginAgentProfileLoaderService.ts)) – Loads profiles contributed by plugins.
- **`ExtraAgentProfileLoaderService`** ([`packages/agent-core-v2/src/workspace/workspaceAgentProfileLoader/extraAgentProfileLoaderService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/workspaceAgentProfileLoader/extraAgentProfileLoaderService.ts)) – Loads optional extra profile files.
- **`ExplicitAgentProfileLoaderService`** ([`packages/agent-core-v2/src/workspace/workspaceAgentProfileLoader/explicitAgentProfileLoaderService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/test/workspace/workspaceResources.test.ts).

### Performing File System Operations

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/workspace/workspaceFs/fsService.ts).

### Loading Agent Profiles

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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/`.