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

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 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 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. The concrete implementation, SessionWorkspaceContextService, resides in 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.

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 and 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 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 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 for the ISessionWorkspaceContext interface. The data contract ISessionWorkspaceInfo and sessionWorkspaceInfoSeed reside in src/session/workspaceInfo/workspaceInfo.ts, while the implementation SessionWorkspaceContextService is located in src/session/workspaceContext/workspaceContextService.ts.

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