ExecContext

ExecContext is primitive #0 — the shared nervous system of a request. It flows through every method in every primitive, carrying identity, permissions, memory scope, observability, and lifecycle state.

Why It Exists

Without ExecContext, you end up with one of two outcomes:

1. Argument explosion — every function takes 6+ separate parameters for user ID, trace ID, permissions, memory scope, timeout, and streaming
2. God object later — you build a request context object in v2 after the codebase becomes unmanageable

ExecContext makes this explicit from day one.

What It Carries

Identity

Python

ctx.request_id   # unique per request
ctx.trace_id     # groups related requests (multi-turn conversation)
ctx.user_id      # who is asking
ctx.session_id   # conversation session

TypeScript

ctx.requestId   // unique per request
ctx.traceId     // groups related requests (multi-turn conversation)
ctx.userId      // who is asking
ctx.sessionId   // conversation session

Go

ctx.RequestID   // unique per request
ctx.TraceID     // groups related requests (multi-turn conversation)
ctx.UserID      // who is asking
ctx.SessionID   // conversation session

Permissions

Python

ctx.permissions   # what this user/agent can access
ctx.permissions.can_use_tool("search_flights")   # check tool access
ctx.permissions.can_use_agent("flight_agent")    # check agent access
ctx.permissions.has_role("admin")                # check role

TypeScript

ctx.permissions   // what this user/agent can access
ctx.permissions.canUseTool("search_flights")   // check tool access
ctx.permissions.canUseAgent("flight_agent")    // check agent access
ctx.permissions.hasRole("admin")               // check role

Go

ctx.Permissions   // what this user/agent can access
ctx.Permissions.CanUseTool("search_flights")   // check tool access
ctx.Permissions.CanUseAgent("flight_agent")    // check agent access
ctx.Permissions.HasRole("admin")               // check role

Memory Scope

Python

ctx.memory_scope  # "user" | "session" | "agent" | "global"

TypeScript

ctx.memoryScope  // "user" | "session" | "agent" | "global"

Go

ctx.MemoryScope  // ScopeUser | ScopeSession | ScopeAgent | ScopeGlobal

Memory operations are automatically scoped — user A’s context never leaks to user B.

Observability

Python

ctx.spans          # OpenTelemetry-compatible trace spans
ctx.events         # structured log events
ctx.token_usage    # accumulated LLM token counts across all calls

TypeScript

ctx.spans          // OpenTelemetry-compatible trace spans
ctx.events         // structured log events
ctx.tokenUsage     // accumulated LLM token counts across all calls

Go

ctx.Spans()        // OpenTelemetry-compatible trace spans (returns a copy)
ctx.Events()       // structured log events (returns a copy)
ctx.TokenUsage     // accumulated LLM token counts across all calls

Lifecycle

Python

ctx.created_at     # when the request started
ctx.timeout_at     # when it should be killed
ctx.cancelled      # cooperative cancellation event (asyncio.Event)
ctx.is_timed_out() # check if timeout exceeded
ctx.is_cancelled() # check if cancellation signalled

TypeScript

ctx.createdAt      // when the request started
ctx.timeoutAt      // when it should be killed
ctx.cancelSignal   // AbortSignal for cooperative cancellation
ctx.isTimedOut()   // check if timeout exceeded
ctx.isCancelled()  // check if cancellation signalled

Go

ctx.CreatedAt      // when the request started
ctx.TimeoutAt      // when it should be killed (*time.Time, nil if no timeout)
ctx.Context()      // underlying context.Context for cancellation
ctx.IsTimedOut()   // check if timeout exceeded
ctx.IsCancelled()  // check if cancellation signalled

Streaming

Python

ctx.stream         # if set, primitives push tokens here as they are produced

TypeScript

ctx.stream         // if set, primitives push tokens here as they are produced

Go

// Go uses the standard context.Context pattern for streaming.
// Pass a StreamSink via ctx.Metadata or a custom wrapper.

Creating a Context

Python

from nerva import ExecContext

# Minimal
ctx = ExecContext.create(user_id="user_123")

# Full control
ctx = ExecContext.create(
    user_id="user_123",
    session_id="session_abc",
    permissions=my_permissions,
    memory_scope="session",
    timeout_seconds=30,
)

TypeScript

import { ExecContext } from "nerva";

// Minimal
const ctx = ExecContext.create({ userId: "user_123" });

// Full control
const ctx = ExecContext.create({
  userId: "user_123",
  sessionId: "session_abc",
  permissions: myPermissions,
  memoryScope: "session",
  timeoutSeconds: 30,
});

Go

import nctx "github.com/otomus/nerva/go/context"

// Minimal
ctx := nctx.NewContext(nctx.WithUserID("user_123"))

// Full control
ctx := nctx.NewContext(
    nctx.WithUserID("user_123"),
    nctx.WithSessionID("session_abc"),
    nctx.WithPermissions(myPermissions),
    nctx.WithMemoryScope(nctx.ScopeSession),
    nctx.WithTimeout(30),
)

Tip

ExecContext is the one thing that ties everything together. If you only learn one concept in Nerva, make it this one — every primitive method receives it, and it replaces the 6+ separate arguments you would otherwise need.

Who Uses It

Every primitive receives ExecContext and uses the parts it needs:

Primitive	What it reads from ExecContext
Router	permissions — permission-aware handler selection
Runtime	timeout_at, cancelled, spans — lifecycle and tracing
Tools	permissions — which tools this user/agent can call
Memory	memory_scope, session_id, user_id — scope isolation
Responder	stream — streaming vs batch mode
Registry	permissions — filtered discovery
Policy	token_usage, user_id — budget and rate limit evaluation

Framework Bridge

When Nerva runs inside FastAPI, NestJS, or Express, you bridge your framework’s auth into ExecContext:

Python

# FastAPI — map JWT user to Nerva context
@app.post("/chat")
async def chat(req: ChatRequest, user: User = Depends(get_current_user)):
    ctx = ExecContext.create(
        user_id=user.id,
        session_id=req.session_id,
        permissions=permissions_from_user(user),
    )
    return await orchestrator.handle(req.message, ctx)

TypeScript

// Express — map JWT user to Nerva context
app.post("/chat", async (req, res) => {
  const user = await getCurrentUser(req);
  const ctx = ExecContext.create({
    userId: user.id,
    sessionId: req.body.sessionId,
    permissions: permissionsFromUser(user),
  });
  const result = await orchestrator.handle(req.body.message, ctx);
  res.json(result);
});

Go

// net/http — map JWT user to Nerva context
func chatHandler(w http.ResponseWriter, r *http.Request) {
    user := getCurrentUser(r)
    ctx := nctx.NewContext(
        nctx.WithUserID(user.ID),
        nctx.WithSessionID(req.SessionID),
        nctx.WithPermissions(permissionsFromUser(user)),
    )
    result, err := orchestrator.Handle(ctx, req.Message)
    json.NewEncoder(w).Encode(result)
}

The contrib helpers (nerva.contrib.fastapi, nerva/contrib/express, nerva/contrib/nestjs) automate this bridge.

Note

When you create a child context via runtime.delegate(), the child inherits the parent’s trace ID, permissions, and memory scope. This means permission checks and observability work automatically across agent-to-agent calls.