# How to Access Workspace-Scoped Services from a Session in agent-core-v2

> Learn how to access workspace scoped services from a session in agent-core-v2. Discover Kimi Code's dependency injection for seamless service resolution.

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

---

**You can retrieve workspace-scoped services directly from a session's accessor because agent-core-v2 implements a hierarchical dependency injection container where the Workspace scope acts as the parent of the Session scope, enabling automatic service resolution up the container chain.**

The `agent-core-v2` package in the [MoonshotAI/kimi-code](https://github.com/MoonshotAI/kimi-code) repository implements a sophisticated scoping mechanism that allows sessions to inherit workspace-level dependencies. When you need to access workspace-scoped services from a session in agent-core-v2, the DI container handles the resolution automatically by walking up the scope hierarchy from Session to Workspace.

## Understanding the Hierarchical DI Scope Chain

The architecture relies on two primary lifecycle scopes: **Workspace** and **Session**. When initializing the host container, you create a workspace child scope first, then spawn a session as a child of that workspace. This parent-child relationship means that any service registered with `LifecycleScope.Workspace` becomes available to all sessions created under that workspace.

The container creation pattern works as follows:

1. Create the workspace scope using `host.child(LifecycleScope.Workspace, ...)`.
2. Create the session scope using `workspace.child(LifecycleScope.Session, ...)`.

This hierarchy ensures that when a session requests a service not found in its own scope, the container falls back to the parent workspace scope.

## Workspace Context Contracts and Data Seeding

Before accessing services, the session must receive workspace metadata through **seeding**. The `sessionWorkspaceInfoSeed` function in [`src/session/workspaceInfo/workspaceInfo.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/session/workspaceInfo/workspaceInfo.ts) creates a scope seed containing the `ISessionWorkspaceInfo` data contract. This seed provides the workspace's cwd, root directory, and additional paths to the session.

The runtime API for interacting with workspace context is defined by the `ISessionWorkspaceContext` interface in [`src/session/workspaceContext/workspaceContext.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/session/workspaceContext/workspaceContext.ts). The concrete implementation, `SessionWorkspaceContextService`, resides in [`src/session/workspaceContext/workspaceContextService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/session/workspaceContext/workspaceContextService.ts) and handles path resolution and service coordination.

## Accessing Workspace-Scoped Services from a Session

To access a workspace-scoped service, simply use the session's accessor. The container automatically resolves services registered with `registerScopedService(LifecycleScope.Workspace, ...)` even when requested from a session context.

```typescript
import { makeHost } from '#/test/harness';
import { LifecycleScope } from '#/di';
import { IWorkspaceSkillCatalog } from '#/workspace/workspaceSkillCatalog/workspaceSkillCatalog';
import { IWorkspaceMcpService } from '#/workspace/workspaceMcp/workspaceMcp';
import { ISessionWorkspaceContext } from '#/session/workspaceContext/workspaceContext';

// Create hierarchical scopes
const workspace = host.child(LifecycleScope.Workspace, 'workspace-1', [
  // workspace seeds and services
]);
const session = workspace.child(LifecycleScope.Session, 'session-1', [
  // session-specific seeds
]);

// Access workspace-scoped services directly from session
const skillCatalog = session.accessor.get(IWorkspaceSkillCatalog);
const mcpService = session.accessor.get(IWorkspaceMcpService);

// Access workspace context for path resolution
const wsContext = session.accessor.get(ISessionWorkspaceContext);
const absolutePath = wsContext.resolve('src/index.ts');

```

In this example, `skillCatalog` and `mcpService` are registered at the Workspace scope, yet the session accessor retrieves them seamlessly by climbing the scope chain.

## Real-World Usage in Tools and Tests

This pattern appears throughout the codebase. In [`src/agent/tools/os/read/readTool.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/agent/tools/os/read/readTool.ts) and [`src/agent/tools/os/write/writeTool.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/agent/tools/os/write/writeTool.ts), tools inject `ISessionWorkspaceContext` to resolve file paths against the workspace root. Test suites like [`test/session/terminal/terminalService.test.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/test/session/terminal/terminalService.test.ts) demonstrate accessing the workspace context within session-scoped tests.

The `registerScopedService` function allows modules to register services at the Workspace level, making them available to all child sessions without explicit passing. This design ensures that workspace-level resources like skill catalogs and MCP services remain singletons per workspace while being accessible to every session.

## Summary

- **Hierarchical DI**: agent-core-v2 uses parent-child scopes where Workspace is the parent of Session.
- **Automatic Resolution**: Session accessors automatically resolve workspace-scoped services by walking up the container chain.
- **Seeding**: Use `sessionWorkspaceInfoSeed` from [`src/session/workspaceInfo/workspaceInfo.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/session/workspaceInfo/workspaceInfo.ts) to inject workspace metadata into sessions.
- **Key Contracts**: `ISessionWorkspaceContext` and `SessionWorkspaceContextService` provide the runtime API for workspace interaction.
- **Practical Access**: Retrieve any workspace service via `session.accessor.get(ServiceIdentifier)` regardless of where the service is registered.

## Frequently Asked Questions

### How does the DI container resolve workspace services when requested from a session?

The container implements a hierarchical lookup mechanism. When `session.accessor.get()` is called with a service identifier, it first checks the Session scope. If not found, it automatically traverses to the parent Workspace scope and returns the instance registered there, as implemented in the scope resolution logic.

### What is the purpose of sessionWorkspaceInfoSeed in agent-core-v2?

`sessionWorkspaceInfoSeed` creates a scope seed that injects the `ISessionWorkspaceInfo` data contract into the session's DI container. This seed carries workspace metadata including cwd, root path, and additional directories, making this information available to the session and any workspace-scoped services it consumes.

### Can a session override a workspace-scoped service with its own implementation?

Yes, if a service is registered with `LifecycleScope.Session` using the same service identifier, the session-scoped implementation takes precedence for that specific session. The container always checks the current scope before falling back to parent scopes.

### Which files define the workspace context contracts in agent-core-v2?

The primary contracts are defined in [`src/session/workspaceContext/workspaceContext.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/session/workspaceContext/workspaceContext.ts) for the `ISessionWorkspaceContext` interface. The data contract `ISessionWorkspaceInfo` and `sessionWorkspaceInfoSeed` reside in [`src/session/workspaceInfo/workspaceInfo.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/session/workspaceInfo/workspaceInfo.ts), while the implementation `SessionWorkspaceContextService` is located in [`src/session/workspaceContext/workspaceContextService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/session/workspaceContext/workspaceContextService.ts).