Where to Find the Scope Topology Declaration in agent-core-v2

The scope topology declaration in agent-core-v2 is located in packages/agent-core-v2/src/_base/di/scope.ts within the exported declareScopeTopology function, which initializes the global _scopeTopology array that governs the hierarchical order of scope kinds.

The agent-core-v2 package in the MoonshotAI/kimi-code repository implements a strict hierarchical dependency injection system where scopes must follow a defined topology. Understanding where this topology is declared is essential for correctly initializing the application's container hierarchy and preventing illegal scope nesting.

The Core Declaration Location

The single source of truth for the scope hierarchy is defined in the dependency injection core of the package. This declaration is process-static, meaning it is set once at startup and enforced globally thereafter.

The _scopeTopology Variable

At line 72 of packages/agent-core-v2/src/_base/di/scope.ts, the topology is stored in a module-level variable:

let _scopeTopology: readonly string[] | undefined;

This variable holds the ordered list of ScopeKind values that defines the hierarchy from root to leaf. The type is readonly to prevent mutation after declaration, and it remains undefined until explicitly set.

The declareScopeTopology Function

The topology is declared via the exported function at line 80:

export function declareScopeTopology(kinds: readonly ScopeKind[]) {
  if (_scopeTopology !== undefined) {
    // Runtime guard against re-declaration with different ordering
    // ... error handling omitted
  }
  // Validate that provided kind list is exhaustive
  // Ensure the topology is a permutation of all kinds
  _scopeTopology = [...kinds];
}

This function performs two critical tasks: it validates that the provided array contains every ScopeKind exactly once, and it prevents subsequent calls from altering the established order. The ScopeKind type is defined at line 55 as 'app' | 'workspace' | 'session' | 'agent'.

How the Topology Enforcement Works

Once declared, the topology is consulted whenever the Scope.createChild method is invoked. The system enforces that child scopes must follow their parents in the declared hierarchy. For example, an 'app' scope can create a 'workspace' child, but a 'workspace' cannot create an 'app' child.

The enforcement logic compares indices within the _scopeTopology array to ensure the child kind appears after the parent kind in the ordered list.

Practical Implementation Example

To initialize the dependency injection system correctly, declare the topology before creating any scopes:

// 1️⃣ Declare the topology once at application startup
import { declareScopeTopology } from '#/agent-core-v2/_base/di/scope';

// The order must include every ScopeKind exactly once
declareScopeTopology(['app', 'workspace', 'session', 'agent']);

// 2️⃣ Create the root 'app' scope
import { createAppScope } from '#/agent-core-v2/_base/di/scope';

const appScope = createAppScope({ id: 'mainApp' });

// 3️⃣ Create a valid child 'workspace' scope
const workspace = appScope.createChild('workspace', 'myWorkspace');

// ❌ Invalid: attempting to create 'app' under 'workspace' throws an error
try {
  workspace.createChild('app', 'illegalApp');
} catch (e) {
  console.error(e.message);
  // Output: "child scope kind 'app' must be greater than parent kind 'workspace'"
}

Related Files in the DI System

The scope topology mechanism spans several key files within the agent-core-v2 package:

• packages/agent-core-v2/src/_base/di/scope.ts – Contains the _scopeTopology declaration, declareScopeTopology function, and the Scope class implementation.
• packages/agent-core-v2/src/_base/di/instantiation.ts – Provides the InstantiationService used by Scope to create child containers and resolve dependencies.
• packages/agent-core-v2/src/_base/di/types.ts – Defines the ScopeKind union type and ScopeOptions interface used throughout the system.

Summary

• The scope topology is declared in packages/agent-core-v2/src/_base/di/scope.ts via the declareScopeTopology function.
• The global state is stored in the _scopeTopology variable, which is typed as readonly string[] | undefined.
• Valid ScopeKind values are 'app', 'workspace', 'session', and 'agent'.
• The topology can only be set once per process; subsequent calls with different orderings will throw errors.
• Child scope creation validates against this topology to enforce hierarchical boundaries.

Frequently Asked Questions

What is the scope topology in agent-core-v2?

The scope topology is a statically declared ordered array of ScopeKind values (app, workspace, session, agent) that defines the legal parent-child relationships in the dependency injection container hierarchy. It ensures that scopes can only be created in a specific descending order, preventing architectural violations where a child scope might incorrectly parent a higher-level scope.

What happens if I call declareScopeTopology twice?

The function guards against re-declaration. If _scopeTopology is already defined and the new kinds array differs from the existing one, the function will throw a runtime error. This prevents multiple parts of the application from accidentally establishing conflicting hierarchies, ensuring a single consistent topology per process.

Where is the topology validated during child scope creation?

The validation occurs within the Scope.createChild method implementation in packages/agent-core-v2/src/_base/di/scope.ts. When createChild is called, the system checks the _scopeTopology array to verify that the requested child kind has a higher index than the current scope's kind. If the check fails, an error is thrown before the container is instantiated.

Why must the topology include all ScopeKinds exactly once?

The declareScopeTopology function validates that the input array is an exhaustive permutation of all available ScopeKind values. This ensures the hierarchy is complete and unambiguous, preventing gaps in the chain that could lead to orphaned scopes or undefined behavior during service resolution across scope boundaries.

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