@robota-sdk/agent-session 3.0.0-beta.64

package/CHANGELOG.md

@@ -0,0 +1,524 @@
+# @robota-sdk/agent-session
+
+## 3.0.0-beta.64
+
+### Patch Changes
+
+- @robota-sdk/agent-core@3.0.0-beta.64
+
+## 3.0.0-beta.63
+
+### Patch Changes
+
+- @robota-sdk/agent-core@3.0.0-beta.63
+
+## 3.0.0-beta.62
+
+### Patch Changes
+
+- Updated dependencies
+  - @robota-sdk/agent-core@3.0.0-beta.62
+
+## 3.0.0-beta.61
+
+### Minor Changes
+
+- 18fcc5b: Add provider-neutral sandbox snapshot hydration for interactive sessions. Snapshot-capable sandbox clients now persist `sandboxSnapshotId` on shutdown and restore it before saved message replay on non-fork resume, while the E2B structural adapter supports both `createSnapshot()`-style checkpoints and pause/resume sandbox references.
+
+### Patch Changes
+
+- 1c0d44c: Align context usage estimation across session display, auto-compaction, and core hard-capacity guards so mid-window sessions do not block prematurely.
+- 36eb7a9: Add provider-owned native replay payload hooks, replay validation coverage, and a session log validation command.
+- d97bdf2: Add provider-owned model catalog metadata, route `/model` suggestions through the active provider, and make `cli:dev` resolve the CLI workspace dependency closure through source export conditions.
+- Updated dependencies [1c0d44c]
+- Updated dependencies [36eb7a9]
+- Updated dependencies [d97bdf2]
+  - @robota-sdk/agent-core@3.0.0-beta.61
+
+## 3.0.0-beta.60
+
+### Minor Changes
+
+- 7439391: Add provider-neutral native web search/fetch capability contracts, explicit unsupported handling for OpenAI-compatible/LM Studio profiles, and local WebFetch/WebSearch permission/documentation alignment.
+
+### Patch Changes
+
+- Updated dependencies [7439391]
+  - @robota-sdk/agent-core@3.0.0-beta.60
+
+## 3.0.0-beta.59
+
+### Patch Changes
+
+- @robota-sdk/agent-core@3.0.0-beta.59
+
+## 3.0.0-beta.58
+
+### Patch Changes
+
+- Refresh package docs and robota.io content for the beta 57 feature set.
+- Updated dependencies
+  - @robota-sdk/agent-core@3.0.0-beta.58
+
+## 3.0.0-beta.57
+
+### Minor Changes
+
+- b80e51e: Add SDK-owned automatic project memory capture, approval review, bounded retrieval, and session-log provenance.
+
+### Patch Changes
+
+- 16c3b6f: Persist and render provider-neutral per-turn usage summaries with pre-send context updates in CLI sessions.
+- 26a1718: Preserve and render Edit tool diff metadata in persisted CLI tool summaries.
+- Updated dependencies [16c3b6f]
+- Updated dependencies [f61e2cb]
+  - @robota-sdk/agent-core@3.0.0-beta.57
+
+## 3.0.0-beta.56
+
+### Patch Changes
+
+- Updated dependencies
+  - @robota-sdk/agent-core@3.0.0-beta.56
+
+## 3.0.0-beta.55
+
+### Patch Changes
+
+- 38a72bf: fix: resolve ESLint tsconfig parsing errors and improve pnpm CI reliability
+  - Add tsconfig.eslint.json to all packages for per-package ESLint runs
+  - Migrate typecheck from pnpm -r exec tsc to per-package typecheck scripts
+  - Add --if-present to all recursive pnpm run scripts
+  - Fix React type imports, dynamic imports in tests, Express.Multer types
+
+- Updated dependencies [38a72bf]
+  - @robota-sdk/agent-core@3.0.0-beta.55
+
+## 3.0.0-beta.54
+
+### Patch Changes
+
+- fix: resolve all typecheck errors across packages
+- Updated dependencies
+  - @robota-sdk/agent-core@3.0.0-beta.54
+
+## 3.0.0-beta.53
+
+### Patch Changes
+
+- refactor: monolith decomposition — all agent-\* files under 300 lines
+- fix: PR #69 code review — session resume tool messages, type SSOT, fork isolation, settings crash, Notification removal, chat validation
+- Updated dependencies
+- Updated dependencies
+  - @robota-sdk/agent-core@3.0.0-beta.53
+
+## 3.0.0-beta.52
+
+### Patch Changes
+
+- @robota-sdk/agent-core@3.0.0-beta.52
+
+## 3.0.0-beta.51
+
+### Patch Changes
+
+- @robota-sdk/agent-core@3.0.0-beta.51
+
+## 3.0.0-beta.50
+
+### Patch Changes
+
+- @robota-sdk/agent-core@3.0.0-beta.50
+
+## 3.0.0-beta.49
+
+### Patch Changes
+
+- @robota-sdk/agent-core@3.0.0-beta.49
+
+## 3.0.0-beta.48
+
+### Patch Changes
+
+- @robota-sdk/agent-core@3.0.0-beta.48
+
+## 3.0.0-beta.47
+
+### Patch Changes
+
+- @robota-sdk/agent-core@3.0.0-beta.47
+
+## 3.0.0-beta.46
+
+### Minor Changes
+
+- feat: session continue/resume — persist, restore, and switch sessions
+  - ISessionRecord.history field (required) for UI timeline restoration
+  - Session.injectMessage() for AI context restoration on resume
+  - InteractiveSession: sessionStore, resumeSessionId, forkSession, getName/setName
+  - CLI: --continue, --resume, --fork-session, --name flags
+  - TUI: /resume (session picker), /rename (session naming)
+  - ListPicker generic component with viewport scrolling
+  - Session name display: input border title, terminal title, StatusBar
+  - Session picker: cwd filtering, date+time, response preview
+  - React key remount for instant session switching
+
+### Patch Changes
+
+- @robota-sdk/agent-core@3.0.0-beta.46
+
+## 3.0.0-beta.45
+
+### Patch Changes
+
+- @robota-sdk/agent-core@3.0.0-beta.45
+
+## 3.0.0-beta.44
+
+### Patch Changes
+
+- feat: IHistoryEntry universal history architecture + test quality cleanup
+  - IHistoryEntry as universal history type across all 4 packages (core → sessions → sdk → cli)
+  - Tool summary stored as event entry in history (category: 'event', type: 'tool-summary')
+  - TuiStateManager pure TypeScript class for CLI rendering state
+  - MessageList renders IHistoryEntry[] with Tool:/System:/You:/Robota: labels
+  - Display order fixed: Tool → Robota (both streaming and abort)
+  - Remove 25 tautological, duplicate, and hardcoded tests
+
+- Updated dependencies
+  - @robota-sdk/agent-core@3.0.0-beta.44
+
+## 2.0.9
+
+### Patch Changes
+
+- Add environment-specific builds and conditional exports for optimal browser compatibility
+
+  This update introduces major build optimizations for better browser performance:
+
+  ## 🚀 Environment-Specific Builds
+  - **Node.js builds**: `dist/node/` with full ESM and CJS support
+  - **Browser builds**: `dist/browser/` with optimized ESM bundles
+  - **Automatic selection**: Bundlers automatically choose the right build
+
+  ## 📦 Bundle Size Optimizations
+  - **team package**: 36% smaller browser bundles (37.52KB → 24.12KB)
+  - **sessions package**: 48% smaller browser bundles (10.64KB → 5.55KB)
+  - **Tree-shaking**: Eliminates Node.js-specific code from browser builds
+  - **Production optimizations**: Removes console logs and debug code in browser builds
+
+  ## 🔧 Conditional Exports
+
+  All packages now support conditional exports for seamless environment detection:
+
+  ```json
+  {
+    "exports": {
+      "node": "./dist/node/index.js",
+      "browser": "./dist/browser/index.js",
+      "default": "./dist/node/index.js"
+    }
+  }
+  ```
+
+  ## 🌐 Enhanced Browser Support
+  - **Zero breaking changes**: Existing code continues to work unchanged
+  - **Better performance**: Optimized bundles for faster loading
+  - **Smaller footprint**: Reduced JavaScript bundle sizes for web applications
+  - **Universal API**: Same API works across all environments
+
+  This update completes the browser compatibility optimization phase, making Robota SDK production-ready for web applications with optimal performance characteristics.
+
+- Updated dependencies
+  - @robota-sdk/agent-core@2.0.9
+
+## 2.0.8
+
+### Patch Changes
+
+- # Model Configuration Refactoring
+
+  ## 🚀 **Breaking Changes**
+
+  ### **Provider Interface Simplification**
+  - **OpenAI Provider**: Removed `model`, `temperature`, `maxTokens`, `topP` from provider options
+  - **Anthropic Provider**: Removed `model`, `temperature`, `maxTokens` from provider options
+  - **Google Provider**: Removed `model`, `temperature`, `maxTokens` from provider options
+  - **All Providers**: `client` is now optional, automatically created from `apiKey`
+
+  ### **Centralized Model Configuration**
+  - Model configuration is now exclusively handled through `defaultModel` in Robota constructor
+  - Providers are simplified to handle only connection-related settings
+  - Runtime model switching via `setModel()` method is now the recommended approach
+
+  ## ✨ **Improvements**
+
+  ### **Simplified Provider Creation**
+
+  ```typescript
+  // Before
+  const provider = new OpenAIProvider({
+    client: openaiClient,
+    model: 'gpt-3.5-turbo',
+  });
+
+  // After
+  const provider = new OpenAIProvider({
+    apiKey: process.env.OPENAI_API_KEY,
+  });
+  ```
+
+  ### **Enhanced Validation**
+  - Added strict validation for required model configuration
+  - Removed default model fallbacks to prevent ambiguous behavior
+  - Clear error messages when model is not specified
+
+  ### **Documentation Updates**
+  - Updated all README files with new usage patterns
+  - Regenerated API documentation
+  - Updated all example files (11 examples)
+
+  ## 🔧 **Migration Guide**
+  1. **Remove model settings from Provider constructors**
+  2. **Use `apiKey` instead of `client` injection (recommended)**
+  3. **Ensure `defaultModel` is properly configured in Robota constructor**
+  4. **Update any hardcoded model references to use runtime switching**
+
+  ## 🎯 **Benefits**
+  - **Eliminates configuration confusion** - Single source of truth for models
+  - **Simplifies provider setup** - Just provide API credentials
+  - **Enables better runtime control** - Centralized model management
+  - **Improves consistency** - All providers follow same pattern
+
+- Updated dependencies
+  - @robota-sdk/agent-core@2.0.8
+
+## 2.0.7
+
+### Patch Changes
+
+- Browser compatibility improvements
+  - feat: Implement SimpleLogger system to replace direct console usage for better browser compatibility
+  - feat: Centralize SimpleLogger in @robota-sdk/agent-core package and export for other packages
+  - feat: Add support for silent and stderr-only logging modes via SilentLogger and StderrLogger
+  - refactor: Update all packages (@robota-sdk/agent-provider-openai, @robota-sdk/agent-provider-anthropic, etc.) to use centralized SimpleLogger
+  - chore: Add ESLint rules to prevent direct console usage while allowing legitimate cases
+  - fix: Remove unused AIProvider import from examples to clean up warnings
+
+  These changes ensure the SDK works properly in browser environments by removing Node.js-specific console behavior while maintaining full backward compatibility.
+
+- Updated dependencies
+  - @robota-sdk/agent-core@2.0.7
+
+## 2.0.6
+
+### Patch Changes
+
+- Add browser compatibility by removing Node.js dependencies
+  - Replace NodeJS.Timeout with cross-platform TimerId type
+  - Remove process.env dependency from logger configuration
+  - Replace Node.js crypto module with jsSHA library for webhook signatures
+  - Update OpenAI stream handlers to work in browser environments
+  - Maintain 100% backward compatibility with existing Node.js applications
+
+  This update enables Robota SDK to run seamlessly in both Node.js and browser environments without breaking changes.
+
+- Updated dependencies
+  - @robota-sdk/agent-core@2.0.6
+
+## 2.0.5
+
+### Patch Changes
+
+- ## 🎯 TypeScript Declaration File Optimization
+- Updated dependencies
+  - @robota-sdk/agent-core@2.0.5
+
+## 2.0.4
+
+### Patch Changes
+
+- 9f17ac6: Restore README.md files and prevent deletion during build process
+- Updated dependencies [9f17ac6]
+  - @robota-sdk/agent-core@2.0.4
+
+## 2.1.0
+
+### Minor Changes
+
+- **Production-Ready Architecture**: Complete refactoring from experimental to production-ready state
+  - **Purpose Redefinition**: Focused on managing multiple independent AI agents in isolated workspaces
+  - **Removed Message Editing**: Eliminated message editing/deletion functionality to focus on core purpose
+  - **Simplified Architecture**: ChatInstance now wraps Robota agents with clean delegation
+  - **SessionManager Implementation**: Complete multi-session management with workspace isolation
+  - **Template Integration**: Integrated with agents package AgentFactory and AgentTemplates
+  - **File Cleanup**: Removed duplicate implementations that existed in agents package
+  - **Type System Simplification**: Streamlined interfaces and removed complex EnhancedConversationHistory
+  - **Comprehensive Testing**: Added full test coverage and working examples
+  - **Documentation Overhaul**: Complete README rewrite with architecture diagrams and API reference
+
+### Patch Changes
+
+- Updated dependencies
+  - @robota-sdk/agent-core@2.1.0
+
+## 2.0.3
+
+### Patch Changes
+
+- @robota-sdk/agent-core@2.0.3
+
+## 2.0.2
+
+### Patch Changes
+
+- Fix npm package documentation by ensuring README.md files are included
+- Updated dependencies
+  - @robota-sdk/agent-core@2.0.2
+
+## 2.0.1
+
+### Patch Changes
+
+- Remove unused dependencies from agents and sessions packages
+- Updated dependencies
+  - @robota-sdk/agent-core@2.0.1
+
+## 2.0.0
+
+### Major Changes
+
+- a3a464c: # Robota SDK v2.0.0-rc.1 - Unified Architecture
+
+  ## 🚀 Major Changes
+
+  ### New Unified Core
+  - **@robota-sdk/agent-core**: New unified core package consolidating all functionality
+  - **Zero `any` types**: Complete TypeScript type safety across all packages
+  - **Provider-agnostic design**: Seamless switching between OpenAI, Anthropic, and Google
+
+  ### Key Features
+  - **Multi-Provider Support**: Dynamic provider switching with type safety
+  - **Advanced Function Calling**: Type-safe tool system with Zod validation
+  - **Real-time Streaming**: Improved streaming with proper error handling
+  - **Task Delegation**: Improved delegated workflow support
+  - **Plugin Architecture**: Comprehensive plugin system with facade pattern
+
+  ### Breaking Changes
+  - `@robota-sdk/core` functionality moved to `@robota-sdk/agent-core`
+  - Redesigned provider interfaces with generic type parameters
+  - Updated agent configuration format
+
+  Complete architecture overhaul focused on type safety and developer experience.
+
+### Patch Changes
+
+- Updated dependencies [a3a464c]
+  - @robota-sdk/agent-core@2.0.0
+
+## 1.0.5
+
+### Patch Changes
+
+- Simplify team API, update docs, fix lint issues, add task coordinator template
+- Updated dependencies
+  - @robota-sdk/agent-tools@1.0.5
+  - @robota-sdk/core@1.0.5
+
+## 1.0.4
+
+### Patch Changes
+
+- Add task delegation tooling with assignTask MCP tools
+- Updated dependencies
+  - @robota-sdk/core@1.0.4
+  - @robota-sdk/agent-tools@1.0.4
+
+## 1.0.3
+
+### Patch Changes
+
+- Complete examples restructure and enhanced provider architecture
+- Updated dependencies
+  - @robota-sdk/agent-tools@1.0.3
+  - @robota-sdk/core@1.0.3
+
+## 1.0.2
+
+### Patch Changes
+
+- Refactor examples and improve resource management
+  - Simplified examples from 18+ files to 4 core examples (basic conversation, tool calling, multi-providers, advanced features)
+  - Added proper resource cleanup with `robota.close()` method to prevent hanging processes
+  - Implemented `ToolProviderManager.close()` for proper tool provider cleanup
+  - Added BaseAIProvider abstract class with common functionality for all AI providers
+  - Updated package.json scripts and README documentation for better user experience
+  - Removed duplicate and redundant example files
+  - Added .env.example file for easier setup
+
+- Updated dependencies
+  - @robota-sdk/core@1.0.2
+  - @robota-sdk/agent-tools@1.0.2
+
+## 1.0.1
+
+### Patch Changes
+
+- Fix facade pattern tests and conversation history message limits
+- Updated dependencies
+  - @robota-sdk/agent-tools@1.0.1
+  - @robota-sdk/core@1.0.1
+
+## 1.0.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @robota-sdk/agent-tools@1.0.0
+  - @robota-sdk/core@1.0.0
+
+## 0.3.7
+
+### Patch Changes
+
+- Major code quality improvements and architectural refactoring:
+  - **Facade Pattern Implementation**: Simplified Robota class interface with manager-based architecture (ai, system, functions, analytics, tools, limits, conversation)
+  - **Deprecated Methods Removal**: Removed 20+ deprecated methods, replaced with clean option-based constructor
+  - **File Modularization**: Split large files into focused modules (function.ts → 4 modules, conversation-history refactoring)
+  - **State Management Enhancement**: Implemented state machine pattern for sessions with improved error handling
+  - **Pure Function Optimization**: Reduced complexity with pure functions and better separation of concerns
+  - **TypeScript Improvements**: Fixed all compilation errors and improved type safety
+  - **Example Updates**: Updated examples to use new API patterns
+
+  Breaking changes are minimal as the core functionality remains the same, but the internal architecture is significantly cleaner and more maintainable.
+
+- Updated dependencies
+  - @robota-sdk/agent-tools@0.3.7
+  - @robota-sdk/core@0.3.7
+
+## 0.3.6
+
+### Patch Changes
+
+- Update publishing docs with proper deployment guidelines
+- Updated dependencies
+  - @robota-sdk/agent-tools@0.3.6
+  - @robota-sdk/core@0.3.6
+
+## 0.3.5
+
+### Patch Changes
+
+- Fix workspace dependencies & update README docs for all packages
+- Updated dependencies
+  - @robota-sdk/agent-tools@0.3.5
+  - @robota-sdk/core@0.3.5
+
+## 0.3.4
+
+### Patch Changes
+
+- f77f18e: Add sessions package for multi-session & chat management in workspaces
+- Updated dependencies [f77f18e]
+  - @robota-sdk/agent-tools@0.3.4
+  - @robota-sdk/core@0.3.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Robota Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# @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
+
+```bash
+npm install @robota-sdk/agent-session @robota-sdk/agent-core
+```
+
+## Quick Start
+
+```typescript
+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