Skip to content

session-context.md

Latest commit

 

History

History
98 lines (70 loc) · 5.23 KB

session-context.md

File metadata and controls

98 lines (70 loc) · 5.23 KB
Raw
title Session Context
description Use ctx.session and runtime accessors inside eve-managed execution.

eve passes a runtime ctx to tool executors, hook handlers, channel event handlers, and connection auth and header resolvers. Use it to inspect the active session and reach resources bound to that execution.

Accessor Provides Full guide
ctx.session Session identity, turn metadata, auth, and parent lineage This page
ctx.getSandbox() The current agent's live sandbox handle Sandbox
defineState(name, initial) Durable typed state shared by runtime code in one session State

These APIs work only during eve-managed runtime execution. Calling them during module evaluation, discovery, or a build throws.

ctx.session

ctx.session describes the durable session and active turn:

import { defineTool } from "eve/tools";
import { z } from "zod";

export default defineTool({
  description: "Return the active session metadata.",
  inputSchema: z.object({}),
  async execute(_input, ctx) {
    return {
      sessionId: ctx.session.id,
      turnId: ctx.session.turn.id,
      turnSequence: ctx.session.turn.sequence,
      currentCaller: ctx.session.auth.current?.principalId,
      initiator: ctx.session.auth.initiator?.principalId,
      parentSessionId: ctx.session.parent?.sessionId,
      parentCallId: ctx.session.parent?.callId,
    };
  },
});

Public fields include:

  • id: the durable session ID.
  • turn.id: the current turn ID.
  • turn.sequence: the turn's position in the session.
  • auth.current: the caller for the active inbound turn.
  • auth.initiator: the caller that started the session.
  • parent: the parent call, session, root session, and turn for a child subagent session.
  • predecessor: present only when this session replaced a stranded one; sessionId names that earlier session. See Recover a stranded session to read its earlier conversation.

Unprotected agents expose auth.current and auth.initiator as null. Top-level schedule sessions use the framework app principal (principalId: "eve:app", principalType: "runtime"). See Authentication for how inbound identity becomes session auth.

ctx.getSandbox()

Call ctx.getSandbox() when authored runtime code needs filesystem or process access in the current agent's sandbox:

const sandbox = await ctx.getSandbox();
const result = await sandbox.run({ command: "npm test" });

The accessor is asynchronous because eve may need to bind or restore the sandbox. A subagent sees its own sandbox, not its parent's. The returned handle also exposes stop() and delete(); see Sandbox lifecycle for their behavior.

When you need capabilities specific to the configured environment, pass its exported environment object. The return type preserves the environment's session capabilities. Provider-specific methods such as setNetworkPolicy() are not available from the no-argument accessor:

import { environment } from "../sandbox";

const sandbox = await ctx.getSandbox(environment);
await sandbox.setNetworkPolicy("deny-all");

The environment must be the one configured for the current sandbox. eve rejects a different environment instead of returning a handle with capabilities that may not exist.

Custom state with defineState

Use defineState for durable per-session values that tools, hooks, and channel handlers share. Unlike the ctx accessors, import it from eve/context and declare the handle at module scope. Its get() and update() methods still require active eve execution. See State for the read, update, reset, and subagent-isolation model.

Where these APIs work

Runtime context is available:

  • inside defineTool(...).execute(input, ctx);
  • inside connection auth and headers resolvers;
  • inside channel and agent hook callbacks that receive the full runtime ctx;
  • after asynchronous boundaries within the same authored execution chain.

Runtime context is not available during top-level module evaluation, build scripts, or discovery. Declare reusable definitions and state handles at module scope, but call their context-dependent methods only from an eve-managed callback.

How it works

eve establishes the managed context before invoking authored runtime code and keeps it available across asynchronous work in that execution chain. The framework binds durable session data and step-local resources, then commits mutable state at the step boundary. Authored code uses the public accessors rather than managing this lifecycle.

What to read next