@falai/agent 1.2.7 → 2.0.0

package/docs/guides/advanced-patterns/publishing.md

@@ -1,186 +0,0 @@
-# Publishing Guide
-
-## Pre-publish Checklist
-
-### 1. Build and Test
-
-```bash
-# Clean previous builds
-rm -rf dist/
-
-# Build the package
-bun run build
-
-# Verify types and linting
-bun typecheck
-bun lint
-
-# Test the build (optional - create a test project)
-npm pack
-# This creates a .tgz file you can test locally
-```
-
-### 2. Version Management
-
-Update version in `package.json`:
-
-```json
-{
-  "version": "0.1.0" // Follow semver: major.minor.patch
-}
-```
-
-**Semver Guidelines:**
-
-- **Patch** (0.1.X): Bug fixes, documentation updates
-- **Minor** (0.X.0): New features, backwards compatible
-- **Major** (X.0.0): Breaking changes
-
-### 3. Verify Package Contents
-
-```bash
-# Dry run to see what will be published
-npm publish --dry-run
-
-# Check the files that will be included
-npm pack --dry-run
-```
-
-Should include:
-
-- ✅ `dist/` - Compiled JavaScript + type definitions
-- ✅ `docs/` - Documentation
-- ✅ `examples/` - Example files
-- ✅ `README.md` - Package documentation
-- ✅ `LICENSE` - MIT license
-
-Should NOT include:
-
-- ❌ `src/*.ts` source files (only .d.ts)
-- ❌ `node_modules/`
-- ❌ Development configs
-
-## Publishing to npm
-
-### First Time Setup
-
-```bash
-# Login to npm (one time)
-npm login
-# Enter your npm credentials
-```
-
-### Publish
-
-```bash
-# Make sure you're on main/master
-git checkout main
-git pull
-
-# Ensure everything is committed
-git status
-
-# Build
-bun run build
-
-# Publish to npm with public access
-npm publish --access public
-
-# Or if you want to test first, use a tag
-npm publish --tag beta --access public
-```
-
-### After Publishing
-
-```bash
-# Tag the release in git
-git tag v0.1.0
-git push origin v0.1.0
-
-# Verify on npm
-npm view @falai/agent
-```
-
-## Post-Publish
-
-1. **Update GitHub Release**
-
-   - Go to https://github.com/falai-dev/agent/releases
-   - Create a new release for the tag
-   - Add release notes
-
-2. **Verify Installation**
-
-   ```bash
-   # In a new project
-   npm install @falai/agent
-   # or
-   bun add @falai/agent
-   ```
-
-3. **Test the Published Package**
-
-   ```bash
-   # Create test project
-   mkdir test-agent && cd test-agent
-   bun init -y
-   bun add @falai/agent
-
-   # Try importing
-   echo 'import { Agent } from "@falai/agent"; console.log(Agent);' > test.ts
-   bun run test.ts
-   ```
-
-## Troubleshooting
-
-### "You do not have permission to publish"
-
-- Make sure you're logged in: `npm whoami`
-- Verify you have access to the `@falai` scope
-- Contact scope owner if needed
-
-### "Package already exists"
-
-- You can't republish the same version
-- Bump version in `package.json` and try again
-
-### "Missing required files"
-
-- Check `package.json` `files` field
-- Ensure `dist/` exists after build
-- Run `npm pack --dry-run` to preview
-
-### Types not working
-
-- Verify `types` field in `package.json`
-- Ensure `.d.ts` files are in `dist/`
-- Check `tsconfig.json` has `"declaration": true`
-
-## Version History
-
-- **0.1.0** - Initial release
-  - Core agent framework
-  - Route DSL
-  - Gemini provider
-  - Full TypeScript support
-  - Declarative configuration
-
-## Useful Commands
-
-```bash
-# Check what version is published
-npm view @falai/agent version
-
-# See all published versions
-npm view @falai/agent versions
-
-# Unpublish a version (within 24 hours, use carefully!)
-npm unpublish @falai/agent@0.1.0
-
-# Deprecate a version (preferred over unpublish)
-npm deprecate @falai/agent@0.1.0 "This version has been deprecated. Please upgrade to 0.2.0"
-```
-
----
-
-**Made with ❤️ for the community**

package/docs/guides/context-compaction.md

@@ -1,96 +0,0 @@
-# Context Compaction
-
-The `CompactionEngine` automatically manages conversation history size when approaching token limits. It applies multi-layered strategies in order of cost, from cheap truncation to LLM-powered summarization.
-
-## Compaction Strategies
-
-Strategies are applied in order until the history fits within the token budget:
-
-| Strategy | Cost | Description |
-|---|---|---|
-| `none` | Free | History is under threshold — no action taken |
-| `tool_result_budget` | Free | Truncate oversized tool results with a notice |
-| `micro_compact` | Free | Collapse whitespace in verbose tool outputs |
-| `auto_compact` | LLM call | Summarize old messages via the configured AI provider |
-
-If the LLM summarization fails, the engine falls back to aggressive truncation (removing oldest messages) and logs a warning. The next compaction attempt will retry summarization.
-
-## Configuration
-
-Compaction is configured at the agent level via the `compaction` option:
-
-```typescript
-import { Agent } from "@falai/agent";
-
-const agent = new Agent({
-  name: "LongConversationAgent",
-  provider: anthropicProvider,
-  compaction: {
-    maxTokens: 100_000,
-    compactionThreshold: 0.8,    // trigger at 80% of budget
-    preserveRecentCount: 10,     // always keep last 10 messages
-    maxToolResultChars: 5_000,   // truncate tool results over 5k chars
-    provider: anthropicProvider, // provider for LLM summarization
-  },
-});
-```
-
-### CompactionOptions
-
-| Option | Type | Constraint | Description |
-|---|---|---|---|
-| `maxTokens` | `number` | > 0 | Maximum token budget for the conversation |
-| `compactionThreshold` | `number` | 0.5 – 0.95 | Ratio at which compaction triggers |
-| `preserveRecentCount` | `number` | ≥ 2 | Recent messages that are never modified |
-| `maxToolResultChars` | `number` | > 0 | Per-tool-result character limit before truncation |
-| `provider` | `AiProvider` | — | Provider used for LLM summarization |
-
-Invalid options throw at construction time.
-
-## How It Works
-
-When the `SessionManager` detects that estimated tokens exceed `maxTokens * compactionThreshold`, the `CompactionEngine` runs:
-
-1. **Token estimation** — character-based heuristic (~4 chars/token), no external tokenizer needed
-2. **Tool result budget** — truncate any tool result exceeding `maxToolResultChars`, append a notice like `[Truncated: 12000 chars total, showing first 5000]`
-3. **Micro-compact** — collapse whitespace in tool outputs for the compactable portion of history
-4. **Auto-compact** — summarize old messages via the AI provider, replacing them with a `[Conversation Summary]` system message
-
-The last `preserveRecentCount` messages are never modified or removed by any strategy.
-
-## Manual Compaction
-
-You can also use the `CompactionEngine` directly:
-
-```typescript
-import { CompactionEngine } from "@falai/agent";
-
-const result = await CompactionEngine.checkAndCompact(history, {
-  maxTokens: 100_000,
-  compactionThreshold: 0.8,
-  preserveRecentCount: 10,
-  maxToolResultChars: 5_000,
-  provider: anthropicProvider,
-});
-
-console.log(result.strategy);        // 'none' | 'tool_result_budget' | 'micro_compact' | 'auto_compact'
-console.log(result.estimatedTokens); // tokens after compaction
-console.log(result.messagesCompacted);
-```
-
-### Standalone Utilities
-
-```typescript
-// Estimate tokens for a history
-const tokens = CompactionEngine.estimateTokens(history);
-
-// Truncate tool results only
-const budgeted = CompactionEngine.applyToolResultBudget(history, 5_000);
-```
-
-## Key Properties
-
-- **Idempotent** — compacting already-compacted history with the same options produces the same result
-- **Deterministic estimation** — `estimateTokens` always returns the same value for the same input
-- **Preservation guarantee** — the last `preserveRecentCount` messages are never touched
-- **Graceful degradation** — LLM failure falls back to truncation, never crashes