Scope

Scope

Edge adaptation of the upstream scope registration and agent-scoped lifecycle vocabulary.

Upstream reference: Scope

What Upstream Provides

The scope package () is a library primitive — not a cordis Service — that provides identity, carrier, and scope-layer vocabulary for agent-scoped registrations:

• ScopeKey — opaque object identity for routing. Agent loops use the object as their key.
  • Scoped<T> — branded type marking scope-filtered event receivers created by . Enables agent-scoped event declarations while keeping the subject explicit.
  • ScopeLayer — one scope's complete contribution to a registry, with vacancy tracking for resource reclamation.
  • ScopedLayers — manages global and lazily-created scope-specific layers. Reading never creates; materializes entries in insertion order. This vocabulary is consumed internally by , , , and other registries that need per-agent visibility. It works like variable scoping in a programming language: resources registered inside an agent's scope are invisible outside it, and are automatically cleaned up when the agent is disposed.

When does scope matter for Edge? Currently it's transparent — Edge has one agent preset and registers all tools at the root Context. Scope becomes critical when implementing:

• Subagent: child agents must not see parent's tools or leak their own tools to the parent.
  • Agent Presets: different sessions with different presets need isolated tool sets.

What Edge Changed

Direct Reuse Scope vocabulary

is a transitive dependency consumed by upstream plugins (AgentRegistry uses , ToolRuntime uses scope-filtered tool visibility). Edge does not import or configure it directly — it works transparently through the upstream plugin stack.

Edge Context Private cordis Context

creates its own private (line 193 of session-store.ts) rather than receiving one from outside. This is an Edge-specific design choice driven by Durable Object lifecycle:

• Each DO activation creates a fresh with a fresh Context
  • All plugins install into this private Context during
  • The Context dies when the DO hibernates or is evicted
  • All workspaces and sessions share this single Context within one DO instance This differs from upstream where a single long-lived Context persists for the Node.js process lifetime.

What Edge Did NOT Change

• ScopeKey identity and routing mechanics
  • Agent-scoped event filtering and visibility
  • ScopeLayer vacancy tracking and resource reclamation
  • How upstream registries (tools, system prompt, projections) use scope layers

Performance Characteristics

Context initialization: Edge creates a fresh Context and installs ~30 plugins on each DO activation. This takes 50–200ms depending on plugin count and storage reads. Subsequent requests within the same activation reuse the initialized Context with zero overhead.

Scope overhead: Scope routing is O(1) per lookup — the is used as a Map key. With typically one agent per session, scope layers add negligible overhead.

Architecture Summary

Component	Category	Edge Code
vocabulary	Reuse	Transitive dependency, not directly imported
Private cordis Context	Replace	per DO activation

Key observation: Scope is invisible infrastructure — Edge neither imports nor configures it. The only Edge-specific aspect is that each DO creates its own short-lived Context instead of sharing a long-lived process Context. This isolation is a natural consequence of the serverless model, not a deliberate adaptation.