@robota-sdk/agent-session

Session lifecycle management for the Robota SDK. Wraps a Robota agent instance with permission-gated tool execution, hook-based lifecycle events, context window tracking, conversation compaction, and optional persistence.

Installation

npm install @robota-sdk/agent-session @robota-sdk/agent-core

Quick Start

import { Session } from '@robota-sdk/agent-session';

const session = new Session({
  tools,
  provider,
  systemMessage: 'You are a helpful assistant.',
  terminal,
  permissions: { allow: ['Read(*)'], deny: [] },
  autoCompactThreshold: 0.75,
});

const response = await session.run('Hello!');

// Context tracking
const state = session.getContextState();
console.log(`${state.usedPercentage.toFixed(1)}% context used`);

// Manual compaction
await session.compact('Focus on the API changes');

Features

| Feature | Description | | -------------------------- | ---------------------------------------------------------------------------------------------------------- | | Permission enforcement | Tool calls gated by 3-step policy (deny list, allow list, mode policy) | | Hook execution | PreToolUse, PostToolUse, PreCompact, PostCompact, SessionStart, Stop | | Context tracking | Effective token usage from the shared core estimator, configurable auto-compact threshold (default ~83.5%) | | Compaction | LLM-generated conversation summary to free context space | | Persistence | SessionStore for JSON file-based session save/load | | Abort | Cancel via session.abort() — propagates AbortSignal to robota.run(), throws AbortError to caller | | Session logging | FileSessionLogger writes JSONL event logs | | Replay events | Provider/tool execution boundary events are forwarded from core into append-only session logs | | Provider capabilities | Generic native web capability setup is requested through the provider contract, not provider-name branches |

Key Methods

| Method | Description | | ------------------------------------------------- | ------------------------------------------------------------------ | | constructor(options) (with sessionId) | Accepts optional sessionId for deterministic IDs | | run(message) | Send a message, returns AI response | | injectMessage(message) | Inject a message into history without running the agent | | compact(instructions?) | Compress conversation via LLM summary | | getContextState() | Effective token usage: { usedTokens, maxTokens, usedPercentage } | | getAutoCompactThreshold() | Auto-compact threshold fraction, or false if disabled | | getPermissionMode() / setPermissionMode(mode) | Read/change permission mode | | getHistory() / clearHistory() | Access or clear conversation history | | abort() | Cancel running execution | | isRunning() | Returns true if a run() call is in progress | | getSessionId() | Returns the stable session identifier | | getMessageCount() | Returns the number of completed run() calls | | getSessionAllowedTools() | Tools approved for this session | | clearSessionAllowedTools() | Clears all session-scoped allow rules |

Public API Surface

| Export | Kind | Description | | ------------------------ | --------- | ------------------------------------------------------------ | | Session | Class | Wraps Robota with permissions, hooks, streaming, persistence | | PermissionEnforcer | Class | Tool permission checking, hook execution, output truncation | | ContextWindowTracker | Class | Effective token usage tracking and auto-compact threshold | | CompactionOrchestrator | Class | Conversation compaction via LLM summary | | SessionStore | Class | JSON file persistence for session records | | FileSessionLogger | Class | JSONL file-based session event logger | | SilentSessionLogger | Class | No-op session logger | | ISessionOptions | Interface | Constructor options for Session | | TAutoCompactThreshold | Type | Auto-compact threshold fraction, or false to disable | | TPermissionHandler | Type | Custom permission approval callback | | TPermissionResult | Type | Permission decision result (boolean \| 'allow-session') | | ITerminalOutput | Interface | Terminal I/O abstraction (write, prompt, select, spinner) | | ISpinner | Interface | Spinner handle | | ISessionLogger | Interface | Pluggable session event logger interface | | TSessionLogData | Type | Structured log event data | | ISessionRecord | Interface | Persisted session record shape (includes history field) | | ISessionStore | Interface | Minimal persistence port implemented by SessionStore | | IContextWindowState | Type | Context window usage state (re-exported from agent-core) |

Note: IPermissionEnforcerOptions is an internal type and is not exported from the public API.

Sub-Components

| Component | Purpose | | ------------------------ | ------------------------------------------------------------------- | | PermissionEnforcer | Tool wrapping, permission checks, hook execution, output truncation | | ContextWindowTracker | Token usage tracking, auto-compact threshold | | CompactionOrchestrator | Conversation summarization via LLM |

Session vs Robota

• Robota (agent-core): Raw agent — conversation + tools + plugins. No permissions, no hooks.
• Session (this package): Wraps Robota with permissions, hooks, compaction, and persistence. Used by the CLI and SDK.

ISessionRecord

ISessionRecord includes a required history field (IHistoryEntry[]) that stores the full conversation timeline for session persistence, resume, and fork operations. It may also include backgroundTasks and backgroundTaskEvents so background work can be restored and debugged alongside the conversation. When a session is resumed, history entries are replayed via Session.injectMessage().

Streaming text deltas are written to append-only JSONL session logs as text_delta events. Consumers should store high-frequency streaming chunks in JSONL logs/transcripts and keep session JSON focused on resumable snapshots and references.

Replay-Oriented JSONL Events

Session.run() forwards core execution events into the session logger through onExecutionEvent. Current events include:

• provider_request
• provider_native_raw_payload
• provider_stream_raw_delta
• provider_response_raw
• provider_response_normalized
• assistant_message_committed
• tool_batch_started
• tool_execution_request
• tool_execution_result
• tool_message_committed
• history_mutation

FileSessionLogger redacts common secret fields before writing logs and stores large fields as content-addressed JSON payload references under {sessionId}.payloads/. session-log-replay exports replay readers and validators that reconstruct chat history from history_mutation and report missing provider/tool terminal events. Replay validation now also requires provider-native raw response or stream payload coverage for each provider_request.

A migration script is available for upgrading session records from older formats. See the package source for details.

Assembly

Most users should use createSession() from @robota-sdk/agent-framework instead of constructing Session directly. The SDK factory wires tools, provider, and system prompt automatically from config and context.

Dependencies

• @robota-sdk/agent-core (production) — Robota agent, permission system, hook system, core types

License

MIT