@axiom-lattice/gateway 3.0.2 → 3.0.3

package/RESUME_STREAM_README.md

@@ -1,388 +0,0 @@
-# Resume Stream Feature
-
-## Overview
-
-The `resume_stream` feature allows you to continue receiving streaming chunks from a known position. This is particularly useful for scenarios where the client connection is interrupted (e.g., page refresh, network issues) and you want to seamlessly continue from where you left off.
-
-## Architecture
-
-### ChunkBuffer Integration
-
-The feature leverages the `ChunkBuffer` module from `@axiom-lattice/core` to:
-
-- Store streaming chunks in memory
-- Track thread status (active/completed/aborted)
-- Provide TTL-based automatic cleanup
-- Calculate and return only new chunks since a known position
-
-### How It Works
-
-```
-┌─────────────────┐
-│  Original       │
-│  Streaming      │ ──► Chunks stored in ChunkBuffer
-│  (agent_stream) │     (thread_id, message_id, content)
-└─────────────────┘
-         │
-         │ Connection lost / Page refresh
-         │
-         ▼
-┌─────────────────┐
-│  Resume Stream  │
-│  (from known    │ ──► Polls for new chunks
-│  position)      │     Returns only new content
-└─────────────────┘     Ends when thread completes
-```
-
-## API Reference
-
-### `resume_stream(options)`
-
-Creates an async iterator that yields new chunks as they arrive.
-
-#### Parameters
-
-```typescript
-{
-  thread_id: string;        // Thread identifier
-  message_id: string;       // Message identifier (usually run_id)
-  known_content: string;    // Content already received (used to find resume position)
-  poll_interval?: number;   // Polling interval in ms (default: 100)
-}
-```
-
-#### Returns
-
-An async iterable object with `Symbol.asyncIterator`:
-
-```typescript
-{
-  content: string; // Chunk content
-  timestamp: number; // When chunk was added
-  messageId: string; // Message identifier
-}
-```
-
-#### Behavior
-
-- **Polling**: Checks for new chunks every `poll_interval` milliseconds
-- **Status Check**: Monitors thread status (active/completed/aborted)
-- **Timeout**: Automatically stops after 30 seconds of no new data
-- **Completion**: Exits when thread is no longer active
-
-## Usage Examples
-
-### Example 1: Basic Resume After Page Refresh
-
-```typescript
-import {
-  resume_stream,
-  get_accumulated_content,
-} from "./services/agent_service";
-
-// Client already received content before refresh (e.g., from localStorage or state)
-const knownContent = "Hello world! This is content I already received...";
-
-const stream = await resume_stream({
-  thread_id: "thread-123",
-  message_id: "msg-abc-456",
-  known_content: knownContent,
-});
-
-// Consume new chunks
-for await (const chunk of stream) {
-  console.log("New content:", chunk.content);
-  displayInUI(chunk.content); // Update your UI
-}
-
-console.log("Stream completed!");
-```
-
-### Example 2: Check Status Before Resuming
-
-```typescript
-import { get_thread_status, resume_stream } from "./services/agent_service";
-
-// Check thread status first
-const status = await get_thread_status("thread-123");
-
-if (!status.exists) {
-  console.log("Thread not found or expired");
-} else if (status.status === "completed") {
-  // Thread already finished, get full content
-  const content = await get_accumulated_content("thread-123");
-  displayFullContent(content);
-} else if (status.status === "active") {
-  // Thread still streaming, resume from current position
-  const currentContent = await get_accumulated_content("thread-123");
-
-  const stream = await resume_stream({
-    thread_id: "thread-123",
-    message_id: "msg-123",
-    known_content: currentContent,
-  });
-
-  for await (const chunk of stream) {
-    appendToUI(chunk.content);
-  }
-}
-```
-
-### Example 3: Express/Fastify Endpoint (SSE)
-
-```typescript
-import express from "express";
-import { resume_stream } from "./services/agent_service";
-
-const app = express();
-
-app.post("/api/resume-stream", async (req, res) => {
-  const { thread_id, message_id, known_content } = req.body;
-
-  // Set up Server-Sent Events
-  res.setHeader("Content-Type", "text/event-stream");
-  res.setHeader("Cache-Control", "no-cache");
-  res.setHeader("Connection", "keep-alive");
-
-  try {
-    const stream = await resume_stream({
-      thread_id,
-      message_id,
-      known_content,
-    });
-
-    for await (const chunk of stream) {
-      res.write(`data: ${JSON.stringify(chunk)}\n\n`);
-    }
-
-    res.write("event: complete\ndata: {}\n\n");
-    res.end();
-  } catch (error) {
-    res.write(
-      `event: error\ndata: ${JSON.stringify({ error: error.message })}\n\n`
-    );
-    res.end();
-  }
-});
-```
-
-### Example 4: React Hook
-
-```typescript
-import { useState, useEffect } from 'react';
-
-function useResumeStream(threadId: string, messageId: string, knownContent: string) {
-  const [content, setContent] = useState('');
-  const [isStreaming, setIsStreaming] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-
-  useEffect(() => {
-    let isCancelled = false;
-
-    async function startStream() {
-      setIsStreaming(true);
-
-      try {
-        const stream = await resume_stream({
-          thread_id: threadId,
-          message_id: messageId,
-          known_content: knownContent,
-        });
-
-        for await (const chunk of stream) {
-          if (isCancelled) break;
-          setContent(prev => prev + chunk.content);
-        }
-      } catch (err) {
-        if (!isCancelled) {
-          setError(err as Error);
-        }
-      } finally {
-        if (!isCancelled) {
-          setIsStreaming(false);
-        }
-      }
-    }
-
-    startStream();
-
-    return () => {
-      isCancelled = true;
-    };
-  }, [threadId, messageId, knownContent]);
-
-  return { content, isStreaming, error };
-}
-
-// Usage in component
-function ChatMessage({ threadId, messageId, initialContent }) {
-  const { content, isStreaming } = useResumeStream(
-    threadId,
-    messageId,
-    initialContent
-  );
-
-  return (
-    <div>
-      {initialContent + content}
-      {isStreaming && <span className="cursor">▋</span>}
-    </div>
-  );
-}
-```
-
-## Related Functions
-
-### `get_accumulated_content(thread_id)`
-
-Get all accumulated content for a thread.
-
-```typescript
-const content = await get_accumulated_content("thread-123");
-```
-
-### `get_thread_status(thread_id)`
-
-Get thread status and metadata.
-
-```typescript
-const status = await get_thread_status("thread-123");
-// {
-//   exists: true,
-//   status: 'active' | 'completed' | 'aborted',
-//   chunkCount: 42,
-//   createdAt: 1234567890,
-//   updatedAt: 1234567900
-// }
-```
-
-### `get_active_threads()`
-
-Get all currently active threads.
-
-```typescript
-const activeThreads = await get_active_threads();
-// ['thread-1', 'thread-2', 'thread-3']
-```
-
-### `clear_thread_buffer(thread_id)`
-
-Manually clear a thread's buffer.
-
-```typescript
-await clear_thread_buffer("thread-123");
-```
-
-## Configuration
-
-### TTL (Time-To-Live)
-
-Threads are automatically cleaned up after 1 hour of inactivity:
-
-```typescript
-// In agent_service.ts
-const buffer = new InMemoryChunkBuffer({
-  ttl: 60 * 60 * 1000, // 1 hour
-  cleanupInterval: 5 * 60 * 1000, // Clean every 5 minutes
-});
-```
-
-### Polling Interval
-
-Adjust polling frequency based on your needs:
-
-```typescript
-// Fast polling for real-time updates
-const stream = await resume_stream({
-  thread_id: "thread-123",
-  message_id: "msg-123",
-  known_content: knownContent,
-  poll_interval: 50, // Check every 50ms
-});
-
-// Slower polling to reduce server load
-const stream = await resume_stream({
-  thread_id: "thread-123",
-  message_id: "msg-123",
-  known_content: knownContent,
-  poll_interval: 500, // Check every 500ms
-});
-```
-
-### Timeout
-
-The resume stream automatically times out after 30 seconds of no new data:
-
-```typescript
-// In agent_service.ts - resume_stream function
-const maxIdleTime = 30000; // 30 seconds
-```
-
-## Error Handling
-
-### Thread Not Found
-
-```typescript
-const stream = await resume_stream({
-  thread_id: "non-existent",
-  message_id: "msg-123",
-  known_content: "",
-});
-
-// Stream will exit immediately if thread doesn't exist
-for await (const chunk of stream) {
-  // Won't execute
-}
-```
-
-### Network Errors
-
-```typescript
-try {
-  const stream = await resume_stream({
-    thread_id: "thread-123",
-    message_id: "msg-123",
-    known_content: previousContent,
-  });
-
-  for await (const chunk of stream) {
-    displayChunk(chunk);
-  }
-} catch (error) {
-  console.error("Stream error:", error);
-  showErrorToUser("Failed to resume stream");
-}
-```
-
-## Best Practices
-
-1. **Always Check Status First**: Check thread status before attempting to resume
-2. **Store Message ID**: Keep track of the `message_id` (usually `run_id`) with your content
-3. **Preserve Content Exactly**: Store the exact content as received (no formatting/processing)
-4. **Handle Completion**: Be prepared for the stream to end at any time
-5. **Implement Retry Logic**: Add retry mechanism for transient failures
-6. **Set Appropriate Poll Interval**: Balance between responsiveness and server load
-7. **Content Matching**: The algorithm matches content intelligently - exact match, prefix, or suffix
-
-## Performance Considerations
-
-- **Memory Usage**: Chunks are stored in memory (consider TTL for long-running applications)
-- **Polling Overhead**: Lower `poll_interval` increases server load but improves responsiveness
-- **Concurrent Streams**: Multiple resume streams can run concurrently
-- **Cleanup**: Old threads are automatically cleaned up based on TTL
-
-## Limitations
-
-- **In-Memory Only**: Current implementation stores chunks in memory (lost on server restart)
-- **Single Message Per Thread**: Designed for one active message per thread
-- **Content Matching**: Relies on exact content matching (whitespace, encoding must match)
-- **No Persistence**: Chunks are not persisted to disk or database
-- **Performance**: Content matching is O(n) where n is number of chunks
-
-## Future Enhancements
-
-- **Persistent Storage**: Add Redis or database backend for persistence across restarts
-- **WebSocket Support**: Direct WebSocket integration for lower latency
-- **Event-Based Notifications**: Use event emitters instead of polling
-- **Compression**: Compress stored chunks to reduce memory usage
-- **Multi-Message Support**: Handle multiple concurrent messages per thread

package/jest.config.js

@@ -1,72 +0,0 @@
-module.exports = {
-  preset: "ts-jest",
-  testEnvironment: "node",
-  roots: ["<rootDir>/src"],
-  testMatch: ["**/__tests__/**/*.test.ts", "**/?(*.)+(spec|test).ts"],
-  transform: {
-    "^.+\\.ts$": [
-      "ts-jest",
-      {
-        isolatedModules: true,
-      },
-    ],
-  },
-  moduleNameMapper: {
-    "^@axiom-lattice/core$": "<rootDir>/../core/src/index.ts",
-    "^@axiom-lattice/protocols$": "<rootDir>/../protocols/src/index.ts",
-    "^@axiom-lattice/pg-stores$": "<rootDir>/../pg-stores/src/index.ts",
-    "^@axiom-lattice/queue-redis$": "<rootDir>/../queue-redis/src/index.ts",
-    "^@memory_lattice$": "<rootDir>/../core/src/memory_lattice",
-    "^@memory_lattice/(.*)$": "<rootDir>/../core/src/memory_lattice/$1",
-    "^@model_lattice$": "<rootDir>/../core/src/model_lattice",
-    "^@model_lattice/(.*)$": "<rootDir>/../core/src/model_lattice/$1",
-    "^@tool_lattice$": "<rootDir>/../core/src/tool_lattice",
-    "^@tool_lattice/(.*)$": "<rootDir>/../core/src/tool_lattice/$1",
-    "^@store_lattice$": "<rootDir>/../core/src/store_lattice",
-    "^@store_lattice/(.*)$": "<rootDir>/../core/src/store_lattice/$1",
-    "^@agent_lattice$": "<rootDir>/../core/src/agent_lattice",
-    "^@agent_lattice/(.*)$": "<rootDir>/../core/src/agent_lattice/$1",
-    "^@skill_lattice$": "<rootDir>/../core/src/skill_lattice",
-    "^@skill_lattice/(.*)$": "<rootDir>/../core/src/skill_lattice/$1",
-    "^@sandbox_lattice$": "<rootDir>/../core/src/sandbox_lattice",
-    "^@sandbox_lattice/(.*)$": "<rootDir>/../core/src/sandbox_lattice/$1",
-    "^@mcp_lattice$": "<rootDir>/../core/src/mcp_lattice",
-    "^@mcp_lattice/(.*)$": "<rootDir>/../core/src/mcp_lattice/$1",
-    "^@chunk_buffer_lattice$": "<rootDir>/../core/src/chunk_buffer_lattice",
-    "^@chunk_buffer_lattice/(.*)$": "<rootDir>/../core/src/chunk_buffer_lattice/$1",
-    "^@base$": "<rootDir>/../core/src/base",
-    "^@base/(.*)$": "<rootDir>/../core/src/base/$1",
-    "^@services$": "<rootDir>/../core/src/services",
-    "^@services/(.*)$": "<rootDir>/../core/src/services/$1",
-    "^@middlewares$": "<rootDir>/../core/src/middlewares",
-    "^@middlewares/(.*)\.js$": "<rootDir>/../core/src/middlewares/$1",
-    "^@middlewares/(.*)$": "<rootDir>/../core/src/middlewares/$1",
-    "^@deep_agent_new$": "<rootDir>/../core/src/deep_agent_new",
-    "^@deep_agent_new/(.*)$": "<rootDir>/../core/src/deep_agent_new/$1",
-    "^@agent_team$": "<rootDir>/../core/src/agent_team",
-    "^@agent_team/(.*)$": "<rootDir>/../core/src/agent_team/$1",
-    "^@schedule_lattice$": "<rootDir>/../core/src/schedule_lattice",
-    "^@schedule_lattice/(.*)$": "<rootDir>/../core/src/schedule_lattice/$1",
-    "^@queue_lattice$": "<rootDir>/../core/src/queue_lattice",
-    "^@queue_lattice/(.*)$": "<rootDir>/../core/src/queue_lattice/$1",
-    "^@embeddings_lattice$": "<rootDir>/../core/src/embeddings_lattice",
-    "^@embeddings_lattice/(.*)$": "<rootDir>/../core/src/embeddings_lattice/$1",
-    "^@vectorstore_lattice$": "<rootDir>/../core/src/vectorstore_lattice",
-    "^@vectorstore_lattice/(.*)$": "<rootDir>/../core/src/vectorstore_lattice/$1",
-    "^@logger_lattice$": "<rootDir>/../core/src/logger_lattice",
-    "^@logger_lattice/(.*)$": "<rootDir>/../core/src/logger_lattice/$1",
-    "^@util$": "<rootDir>/../core/src/util",
-    "^@util/(.*)$": "<rootDir>/../core/src/util/$1",
-    "^@/(.*)$": "<rootDir>/src/$1",
-    "^@services/(.*)$": "<rootDir>/src/services/$1",
-    "^@utils/(.*)$": "<rootDir>/src/utils/$1",
-    "^@types$": "<rootDir>/src/types/index.ts",
-    "^e2b$": "<rootDir>/src/__tests__/__mocks__/e2b.ts",
-    // Strip .js extension from ESM-style imports (must come after all @-scoped mappings)
-    "^(@.*)[.]js$": "$1",
-    "^(\\.{1,2}/.*)\\.js$": "$1",
-  },
-  collectCoverageFrom: ["src/**/*.ts", "!src/**/*.d.ts", "!src/__tests__/**/*"],
-  coverageReporters: ["text", "lcov", "html"],
-  testTimeout: 30000,
-};