opc-agent 1.2.0 → 1.2.1

package/src/core/streaming.ts

@@ -0,0 +1,195 @@
+import { EventEmitter } from 'events';
+
+// ─── Types ───────────────────────────────────────────────────
+
+export interface StreamChunk {
+  id: string;
+  type: 'text' | 'tool_call' | 'error' | 'done';
+  data: string;
+  timestamp: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface StreamOptions {
+  /** High-water mark for backpressure (default 64 chunks). */
+  highWaterMark?: number;
+  /** Heartbeat interval in ms to keep connection alive (default 15000). */
+  heartbeatInterval?: number;
+}
+
+// ─── StreamableResponse ──────────────────────────────────────
+
+export class StreamableResponse extends EventEmitter {
+  readonly id: string;
+  private chunks: StreamChunk[] = [];
+  private ended = false;
+  private paused = false;
+  private buffer: StreamChunk[] = [];
+  private highWaterMark: number;
+
+  constructor(id: string, options?: StreamOptions) {
+    super();
+    this.id = id;
+    this.highWaterMark = options?.highWaterMark ?? 64;
+  }
+
+  /** Push a chunk. Returns false if backpressure threshold reached. */
+  push(chunk: StreamChunk): boolean {
+    if (this.ended) return false;
+
+    this.chunks.push(chunk);
+
+    if (this.paused) {
+      this.buffer.push(chunk);
+      return this.buffer.length < this.highWaterMark;
+    }
+
+    this.emit('chunk', chunk);
+
+    if (this.chunks.length >= this.highWaterMark) {
+      this.paused = true;
+      this.emit('backpressure');
+      return false;
+    }
+    return true;
+  }
+
+  /** Resume after backpressure — flush buffered chunks. */
+  resume(): void {
+    if (!this.paused) return;
+    this.paused = false;
+    const buffered = this.buffer.splice(0);
+    for (const chunk of buffered) {
+      this.emit('chunk', chunk);
+    }
+    this.emit('drain');
+  }
+
+  end(): void {
+    if (this.ended) return;
+    this.ended = true;
+    if (this.paused) this.resume();
+    this.emit('end');
+  }
+
+  getChunks(): StreamChunk[] {
+    return [...this.chunks];
+  }
+
+  /** Collect all text chunks into a single string. */
+  getText(): string {
+    return this.chunks
+      .filter((c) => c.type === 'text')
+      .map((c) => c.data)
+      .join('');
+  }
+
+  get isEnded(): boolean {
+    return this.ended;
+  }
+
+  get isPaused(): boolean {
+    return this.paused;
+  }
+
+  get length(): number {
+    return this.chunks.length;
+  }
+}
+
+// ─── StreamingManager ────────────────────────────────────────
+
+export class StreamingManager {
+  private streams: Map<string, StreamableResponse> = new Map();
+  private counter = 0;
+
+  /** Create a new stream. */
+  createStream(options?: StreamOptions): StreamableResponse {
+    const id = `stream_${++this.counter}_${Date.now()}`;
+    const stream = new StreamableResponse(id, options);
+    this.streams.set(id, stream);
+    stream.on('end', () => {
+      // Keep ended streams for a bit for late consumers, then clean up
+      setTimeout(() => this.streams.delete(id), 30_000);
+    });
+    return stream;
+  }
+
+  /** Write a text chunk to a stream. */
+  writeChunk(streamId: string, data: string, metadata?: Record<string, unknown>): boolean {
+    const stream = this.streams.get(streamId);
+    if (!stream) return false;
+    return stream.push({
+      id: `chunk_${stream.length}`,
+      type: 'text',
+      data,
+      timestamp: Date.now(),
+      metadata,
+    });
+  }
+
+  /** End a stream. */
+  endStream(streamId: string): void {
+    const stream = this.streams.get(streamId);
+    if (!stream) return;
+    stream.push({
+      id: `chunk_${stream.length}`,
+      type: 'done',
+      data: '',
+      timestamp: Date.now(),
+    });
+    stream.end();
+  }
+
+  /** Get an existing stream. */
+  getStream(streamId: string): StreamableResponse | undefined {
+    return this.streams.get(streamId);
+  }
+
+  /** Format a chunk as an SSE event string. */
+  static formatSSE(chunk: StreamChunk): string {
+    const lines: string[] = [];
+    lines.push(`event: ${chunk.type}`);
+    lines.push(`id: ${chunk.id}`);
+    const payload = JSON.stringify({ data: chunk.data, metadata: chunk.metadata });
+    lines.push(`data: ${payload}`);
+    lines.push('');
+    return lines.join('\n') + '\n';
+  }
+
+  /** Pipe a stream to an SSE-compatible HTTP response (Express-style). */
+  static pipeSSE(
+    stream: StreamableResponse,
+    res: { write(data: string): boolean; end(): void; setHeader?(name: string, value: string): void },
+    options?: StreamOptions,
+  ): void {
+    res.setHeader?.('Content-Type', 'text/event-stream');
+    res.setHeader?.('Cache-Control', 'no-cache');
+    res.setHeader?.('Connection', 'keep-alive');
+
+    const heartbeatMs = options?.heartbeatInterval ?? 15_000;
+    const heartbeat = setInterval(() => {
+      res.write(': heartbeat\n\n');
+    }, heartbeatMs);
+
+    stream.on('chunk', (chunk: StreamChunk) => {
+      const ok = res.write(StreamingManager.formatSSE(chunk));
+      if (!ok && stream.isPaused === false) {
+        // Downstream can't keep up — will resume on drain from stream
+      }
+    });
+
+    stream.on('end', () => {
+      clearInterval(heartbeat);
+      res.end();
+    });
+  }
+
+  get activeCount(): number {
+    let count = 0;
+    for (const s of this.streams.values()) {
+      if (!s.isEnded) count++;
+    }
+    return count;
+  }
+}

package/src/core/types.ts

@@ -1,68 +1,68 @@
-import { EventEmitter } from 'events';
-
-// ─── Core Types ──────────────────────────────────────────────
-
-export type AgentState = 'init' | 'ready' | 'running' | 'stopped' | 'error';
-
-export interface Message {
-  id: string;
-  role: 'user' | 'assistant' | 'system';
-  content: string;
-  timestamp: number;
-  metadata?: Record<string, unknown>;
-}
-
-export interface AgentContext {
-  agentName: string;
-  sessionId: string;
-  messages: Message[];
-  memory: MemoryStore;
-  metadata: Record<string, unknown>;
-}
-
-export interface SkillResult {
-  handled: boolean;
-  response?: string;
-  confidence: number;
-  metadata?: Record<string, unknown>;
-}
-
-export interface ISkill {
-  name: string;
-  description: string;
-  execute(context: AgentContext, message: Message): Promise<SkillResult>;
-}
-
-export interface IChannel {
-  type: string;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  onMessage(handler: (message: Message) => Promise<Message>): void;
-}
-
-export interface MemoryStore {
-  get(key: string): Promise<unknown>;
-  set(key: string, value: unknown): Promise<void>;
-  getConversation(sessionId: string): Promise<Message[]>;
-  addMessage(sessionId: string, message: Message): Promise<void>;
-  clear(sessionId?: string): Promise<void>;
-}
-
-export interface AgentEvents {
-  'state:change': (from: AgentState, to: AgentState) => void;
-  'message:in': (message: Message) => void;
-  'message:out': (message: Message) => void;
-  'skill:execute': (skill: string, result: SkillResult) => void;
-  'error': (error: Error) => void;
-}
-
-export interface IAgent extends EventEmitter {
-  readonly name: string;
-  readonly state: AgentState;
-  init(): Promise<void>;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  handleMessage(message: Message): Promise<Message>;
-  registerSkill(skill: ISkill): void;
-  bindChannel(channel: IChannel): void;
-}
+import { EventEmitter } from 'events';
+
+// ─── Core Types ──────────────────────────────────────────────
+
+export type AgentState = 'init' | 'ready' | 'running' | 'stopped' | 'error';
+
+export interface Message {
+  id: string;
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  timestamp: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentContext {
+  agentName: string;
+  sessionId: string;
+  messages: Message[];
+  memory: MemoryStore;
+  metadata: Record<string, unknown>;
+}
+
+export interface SkillResult {
+  handled: boolean;
+  response?: string;
+  confidence: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ISkill {
+  name: string;
+  description: string;
+  execute(context: AgentContext, message: Message): Promise<SkillResult>;
+}
+
+export interface IChannel {
+  type: string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  onMessage(handler: (message: Message) => Promise<Message>): void;
+}
+
+export interface MemoryStore {
+  get(key: string): Promise<unknown>;
+  set(key: string, value: unknown): Promise<void>;
+  getConversation(sessionId: string): Promise<Message[]>;
+  addMessage(sessionId: string, message: Message): Promise<void>;
+  clear(sessionId?: string): Promise<void>;
+}
+
+export interface AgentEvents {
+  'state:change': (from: AgentState, to: AgentState) => void;
+  'message:in': (message: Message) => void;
+  'message:out': (message: Message) => void;
+  'skill:execute': (skill: string, result: SkillResult) => void;
+  'error': (error: Error) => void;
+}
+
+export interface IAgent extends EventEmitter {
+  readonly name: string;
+  readonly state: AgentState;
+  init(): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  handleMessage(message: Message): Promise<Message>;
+  registerSkill(skill: ISkill): void;
+  bindChannel(channel: IChannel): void;
+}

package/src/core/versioning.ts

@@ -1,106 +1,106 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import { Logger } from './logger';
-
-// ── Versioning Types ────────────────────────────────────────
-
-export interface VersionEntry {
-  version: string;
-  timestamp: number;
-  description?: string;
-  oadSnapshot: string; // serialized OAD YAML
-}
-
-export interface Migration {
-  fromVersion: string;
-  toVersion: string;
-  migrate: (oad: Record<string, unknown>) => Record<string, unknown>;
-}
-
-// ── Version Manager ─────────────────────────────────────────
-
-export class VersionManager {
-  private versions: VersionEntry[] = [];
-  private migrations: Migration[] = [];
-  private storePath: string;
-  private logger = new Logger('versioning');
-
-  constructor(storePath?: string) {
-    this.storePath = storePath ?? '.opc-versions.json';
-    this.load();
-  }
-
-  private load(): void {
-    try {
-      if (fs.existsSync(this.storePath)) {
-        const data = JSON.parse(fs.readFileSync(this.storePath, 'utf-8'));
-        this.versions = data.versions ?? [];
-      }
-    } catch {
-      this.versions = [];
-    }
-  }
-
-  private save(): void {
-    fs.writeFileSync(this.storePath, JSON.stringify({ versions: this.versions }, null, 2));
-  }
-
-  snapshot(version: string, oadYaml: string, description?: string): void {
-    this.versions.push({
-      version,
-      timestamp: Date.now(),
-      description,
-      oadSnapshot: oadYaml,
-    });
-    this.save();
-    this.logger.info('Version snapshot saved', { version });
-  }
-
-  list(): VersionEntry[] {
-    return [...this.versions];
-  }
-
-  get(version: string): VersionEntry | undefined {
-    return this.versions.find(v => v.version === version);
-  }
-
-  getCurrent(): VersionEntry | undefined {
-    return this.versions[this.versions.length - 1];
-  }
-
-  rollback(version: string): string | null {
-    const entry = this.get(version);
-    if (!entry) {
-      this.logger.warn('Version not found', { version });
-      return null;
-    }
-    this.logger.info('Rolling back to version', { version });
-    return entry.oadSnapshot;
-  }
-
-  registerMigration(migration: Migration): void {
-    this.migrations.push(migration);
-  }
-
-  migrate(oad: Record<string, unknown>, fromVersion: string, toVersion: string): Record<string, unknown> {
-    let current = fromVersion;
-    let result = { ...oad };
-
-    while (current !== toVersion) {
-      const migration = this.migrations.find(m => m.fromVersion === current);
-      if (!migration) {
-        throw new Error(`No migration path from ${current} to ${toVersion}`);
-      }
-      result = migration.migrate(result);
-      current = migration.toVersion;
-      this.logger.info('Migration applied', { from: migration.fromVersion, to: migration.toVersion });
-    }
-
-    return result;
-  }
-
-  clear(): void {
-    this.versions = [];
-    this.save();
-  }
-}
+import * as fs from 'fs';
+import * as path from 'path';
+import { Logger } from './logger';
+
+// ── Versioning Types ────────────────────────────────────────
+
+export interface VersionEntry {
+  version: string;
+  timestamp: number;
+  description?: string;
+  oadSnapshot: string; // serialized OAD YAML
+}
+
+export interface Migration {
+  fromVersion: string;
+  toVersion: string;
+  migrate: (oad: Record<string, unknown>) => Record<string, unknown>;
+}
+
+// ── Version Manager ─────────────────────────────────────────
+
+export class VersionManager {
+  private versions: VersionEntry[] = [];
+  private migrations: Migration[] = [];
+  private storePath: string;
+  private logger = new Logger('versioning');
+
+  constructor(storePath?: string) {
+    this.storePath = storePath ?? '.opc-versions.json';
+    this.load();
+  }
+
+  private load(): void {
+    try {
+      if (fs.existsSync(this.storePath)) {
+        const data = JSON.parse(fs.readFileSync(this.storePath, 'utf-8'));
+        this.versions = data.versions ?? [];
+      }
+    } catch {
+      this.versions = [];
+    }
+  }
+
+  private save(): void {
+    fs.writeFileSync(this.storePath, JSON.stringify({ versions: this.versions }, null, 2));
+  }
+
+  snapshot(version: string, oadYaml: string, description?: string): void {
+    this.versions.push({
+      version,
+      timestamp: Date.now(),
+      description,
+      oadSnapshot: oadYaml,
+    });
+    this.save();
+    this.logger.info('Version snapshot saved', { version });
+  }
+
+  list(): VersionEntry[] {
+    return [...this.versions];
+  }
+
+  get(version: string): VersionEntry | undefined {
+    return this.versions.find(v => v.version === version);
+  }
+
+  getCurrent(): VersionEntry | undefined {
+    return this.versions[this.versions.length - 1];
+  }
+
+  rollback(version: string): string | null {
+    const entry = this.get(version);
+    if (!entry) {
+      this.logger.warn('Version not found', { version });
+      return null;
+    }
+    this.logger.info('Rolling back to version', { version });
+    return entry.oadSnapshot;
+  }
+
+  registerMigration(migration: Migration): void {
+    this.migrations.push(migration);
+  }
+
+  migrate(oad: Record<string, unknown>, fromVersion: string, toVersion: string): Record<string, unknown> {
+    let current = fromVersion;
+    let result = { ...oad };
+
+    while (current !== toVersion) {
+      const migration = this.migrations.find(m => m.fromVersion === current);
+      if (!migration) {
+        throw new Error(`No migration path from ${current} to ${toVersion}`);
+      }
+      result = migration.migrate(result);
+      current = migration.toVersion;
+      this.logger.info('Migration applied', { from: migration.fromVersion, to: migration.toVersion });
+    }
+
+    return result;
+  }
+
+  clear(): void {
+    this.versions = [];
+    this.save();
+  }
+}