Documentation / @agentick/core / SessionOptions

Interface: SessionOptions

Lifecycle callbacks for session execution.

These provide a cleaner alternative to event listeners for common lifecycle events. Callbacks defined on AppOptions are inherited by all sessions; callbacks on SessionOptions override or supplement them.

Example

typescript

const app = createApp(MyAgent, {
  model,
  onTickStart: (tick) => console.log(`Tick ${tick} starting`),
  onComplete: (result) => console.log(`Done: ${result.response}`),
});

// Session can add its own callbacks
const session = app.session({
  onEvent: (event) => { ... }, // Receives all events
});

Extends

LifecycleCallbacks

Properties

devTools?

optional devTools: boolean

Defined in: core/src/app/types.ts:806

Enable DevTools event emission.

When true, lifecycle events (execution_start, tick_start, tick_end, execution_end, fiber_snapshot) are emitted to the DevTools emitter.

Default

false

Example

typescript

// Enable DevTools for debugging
const session = app.session({ devTools: true });

maxTicks?

optional maxTicks: number

Defined in: core/src/app/types.ts:765

Maximum number of ticks for this session. Overrides AppOptions.maxTicks.

metadata?

optional metadata: Record<string, unknown>

Defined in: core/src/app/types.ts:745

Immutable identity labels for this session.

Set at creation time, frozen, never mutated. Use for type/role/origin metadata that identifies what this session IS (e.g. worker, supervisor, shell). The session graph becomes the process table.

onComplete()?

optional onComplete: (result) => void

Defined in: core/src/app/types.ts:87

Called when execution completes successfully.

Parameters

result

SendResult

The final result

Returns

void

Inherited from

LifecycleCallbacks.onComplete

onError()?

optional onError: (error) => void

Defined in: core/src/app/types.ts:93

Called when an error occurs during execution.

Parameters

error

Error

The error that occurred

Returns

void

Inherited from

LifecycleCallbacks.onError

onEvent()?

optional onEvent: (event) => void

Defined in: core/src/app/types.ts:67

Called for every stream event. Use this for fine-grained event handling.

Parameters

event

StreamEvent

Returns

void

Inherited from

LifecycleCallbacks.onEvent

onTickEnd()?

optional onTickEnd: (tick, usage?) => void

Defined in: core/src/app/types.ts:81

Called when a tick ends.

Parameters

tick

number

The tick number

usage?

UsageStats

Token usage for this tick

Returns

void

Inherited from

LifecycleCallbacks.onTickEnd

onTickStart()?

optional onTickStart: (tick, executionId) => void

Defined in: core/src/app/types.ts:74

Called when a tick starts.

Parameters

tick

number

The tick number (1-indexed)

executionId

string

The execution ID

Returns

void

Inherited from

LifecycleCallbacks.onTickStart

parentSessionId?

optional parentSessionId: string

Defined in: core/src/app/types.ts:736

Parent session ID for persistent parent-child relationships.

Used for delegation: a persistent child session that outlives the parent's execution but still knows who created it. Enables session.notifyParent() for child-to-parent inbox delivery.

recording?

optional recording: RecordingMode

Defined in: core/src/app/types.ts:790

Recording mode for time-travel debugging.

'full': Capture everything (fiber tree, COM, model I/O). Best for development.
'lightweight': Only COM output and model I/O. Good for production debugging.
'none': No recording (default). Minimal overhead.

Example

typescript

// Enable full recording for debugging
const session = app.session({ recording: 'full' });

// After execution, get the recording
const recording = session.getRecording();

sessionId?

optional sessionId: string

Defined in: core/src/app/types.ts:727

Explicit session ID (used by App-managed sessions).

signal?

optional signal: AbortSignal

Defined in: core/src/app/types.ts:770

Per-session abort signal.

skillRegistry?

optional skillRegistry: SkillRegistry

Defined in: core/src/app/types.ts:759

Internal

Skill registry for this session — used to resolve session.skill(name, ...) lookups by string name. Normally populated by the App when creating a session. Pass-through here for tests / advanced use.

tools?

optional tools: ExecutableTool<(input, ctx?) => ContentBlock[] | Promise<ContentBlock[]>>[]

Defined in: core/src/app/types.ts:751

Additional tools for this session. Merged with app-level tools (session tools take priority on name conflict).

knob

Functions