@stacknet/stacks 0.1.0

package/src/streaming/component-stream.ts

@@ -0,0 +1,319 @@
+/**
+ * Component Streaming - Artifact streaming adapter
+ *
+ * Converts tool call responses to artifact data stream format
+ */
+
+export interface DataStreamWriter {
+  write(data: { type: string; data: unknown; transient?: boolean }): void;
+}
+
+export interface ArtifactToolCall {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+
+export interface ArtifactToolResult {
+  type: string;
+  id?: string;
+  title?: string;
+  kind?: string;
+  content?: string;
+  message?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Artifact streaming adapter for AI SDK integration
+ */
+export class ComponentStreamAdapter {
+  constructor(private dataStream: DataStreamWriter) {}
+
+  /**
+   * Process tool calls and convert to artifact stream events
+   */
+  processToolCalls(toolCalls: ArtifactToolCall[]): void {
+    if (!toolCalls || toolCalls.length === 0) return;
+
+    for (const toolCall of toolCalls) {
+      try {
+        const args = JSON.parse(toolCall.function.arguments);
+        const toolName = toolCall.function.name;
+
+        switch (toolName) {
+          case 'create_document':
+            this.handleCreateDocument(args, toolCall.id);
+            break;
+          case 'update_document':
+            this.handleUpdateDocument(args, toolCall.id);
+            break;
+          default:
+            console.log(`[ComponentStream] Unknown tool: ${toolName}`);
+        }
+      } catch (error) {
+        console.error('[ComponentStream] Error processing tool call:', error);
+      }
+    }
+  }
+
+  /**
+   * Process tool results
+   */
+  processToolResult(result: ArtifactToolResult): void {
+    try {
+      if (result.type === 'artifact') {
+        this.handleArtifactResult(result);
+      } else if (result.type === 'artifact_update') {
+        this.handleArtifactUpdate(result);
+      }
+    } catch (error) {
+      console.error('[ComponentStream] Error processing tool result:', error);
+    }
+  }
+
+  /**
+   * Stream an artifact with metadata
+   */
+  streamArtifact(artifact: {
+    id: string;
+    kind: string;
+    title: string;
+    content: string;
+  }): void {
+    this.dataStream.write({
+      type: 'data-kind',
+      data: artifact.kind,
+      transient: true,
+    });
+
+    this.dataStream.write({
+      type: 'data-id',
+      data: artifact.id,
+      transient: true,
+    });
+
+    this.dataStream.write({
+      type: 'data-title',
+      data: artifact.title,
+      transient: true,
+    });
+
+    this.dataStream.write({
+      type: 'data-clear',
+      data: null,
+      transient: true,
+    });
+
+    this.streamContent(artifact.content);
+
+    this.dataStream.write({
+      type: 'data-finish',
+      data: null,
+      transient: true,
+    });
+  }
+
+  /**
+   * Stream a text delta
+   */
+  streamTextDelta(delta: string): void {
+    this.dataStream.write({
+      type: 'data-textDelta',
+      data: delta,
+      transient: true,
+    });
+  }
+
+  /**
+   * Stream content in chunks
+   */
+  streamContent(content: string, chunkSize: number = 50): void {
+    const chunks = this.splitIntoChunks(content, chunkSize);
+
+    for (const chunk of chunks) {
+      this.dataStream.write({
+        type: 'data-textDelta',
+        data: chunk,
+        transient: true,
+      });
+    }
+  }
+
+  /**
+   * Signal finish
+   */
+  finish(): void {
+    this.dataStream.write({
+      type: 'data-finish',
+      data: null,
+      transient: true,
+    });
+  }
+
+  private handleCreateDocument(
+    args: { title: string; kind: string; content: string },
+    toolCallId: string
+  ): void {
+    const { title, kind, content } = args;
+    const documentId = `doc_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+
+    console.log(`[ComponentStream] Creating document: ${title} (${kind})`);
+
+    this.streamArtifact({
+      id: documentId,
+      kind,
+      title,
+      content,
+    });
+
+    this.dataStream.write({
+      type: 'tool-result',
+      data: {
+        toolCallId,
+        toolName: 'create_document',
+        result: {
+          id: documentId,
+          title,
+          kind,
+          message: 'Document created successfully',
+        },
+      },
+    });
+  }
+
+  private handleUpdateDocument(
+    args: { id: string; description: string; content: string },
+    toolCallId: string
+  ): void {
+    const { id, description, content } = args;
+
+    console.log(`[ComponentStream] Updating document: ${id}`);
+
+    this.dataStream.write({
+      type: 'data-clear',
+      data: null,
+      transient: true,
+    });
+
+    this.streamContent(content);
+
+    this.dataStream.write({
+      type: 'data-finish',
+      data: null,
+      transient: true,
+    });
+
+    this.dataStream.write({
+      type: 'tool-result',
+      data: {
+        toolCallId,
+        toolName: 'update_document',
+        result: {
+          id,
+          message: `Document updated: ${description}`,
+        },
+      },
+    });
+  }
+
+  private handleArtifactResult(result: ArtifactToolResult): void {
+    const { id, title, kind, content } = result;
+
+    if (!id || !title || !kind || !content) {
+      console.error('[ComponentStream] Invalid artifact result:', result);
+      return;
+    }
+
+    this.streamArtifact({ id, kind, title, content });
+  }
+
+  private handleArtifactUpdate(result: ArtifactToolResult): void {
+    const { content } = result;
+
+    if (!content) {
+      console.error('[ComponentStream] Invalid artifact update:', result);
+      return;
+    }
+
+    this.dataStream.write({
+      type: 'data-clear',
+      data: null,
+      transient: true,
+    });
+
+    this.streamContent(content);
+
+    this.dataStream.write({
+      type: 'data-finish',
+      data: null,
+      transient: true,
+    });
+  }
+
+  private splitIntoChunks(content: string, chunkSize: number): string[] {
+    const chunks: string[] = [];
+    const words = content.split(' ');
+    let currentChunk = '';
+
+    for (let i = 0; i < words.length; i++) {
+      const word = i === 0 ? words[i] : ' ' + words[i];
+
+      if (currentChunk.length + word.length > chunkSize && currentChunk.length > 0) {
+        chunks.push(currentChunk);
+        currentChunk = word.trim();
+      } else {
+        currentChunk += word;
+      }
+    }
+
+    if (currentChunk.length > 0) {
+      chunks.push(currentChunk);
+    }
+
+    return chunks;
+  }
+}
+
+/**
+ * Helper to detect tool calls in a message
+ */
+export function hasToolCalls(message: {
+  tool_calls?: unknown[];
+}): boolean {
+  return !!(
+    message?.tool_calls &&
+    Array.isArray(message.tool_calls) &&
+    message.tool_calls.length > 0
+  );
+}
+
+/**
+ * Helper to extract tool results from content
+ */
+export function extractToolResults(content: string): ArtifactToolResult[] {
+  try {
+    const parsed = JSON.parse(content);
+    if (
+      parsed.type &&
+      (parsed.type === 'artifact' || parsed.type === 'artifact_update')
+    ) {
+      return [parsed];
+    }
+  } catch {
+    // Not JSON
+  }
+  return [];
+}
+
+/**
+ * Factory function
+ */
+export function createComponentStreamAdapter(
+  dataStream: DataStreamWriter
+): ComponentStreamAdapter {
+  return new ComponentStreamAdapter(dataStream);
+}

package/src/streaming/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @stacknet/stacks - Streaming utilities
+ */
+
+export {
+  parseSSEStream,
+  createSSEResponse,
+  SSEWriter,
+  createSSEWriter,
+  type SSEEvent,
+} from './sse';
+
+export {
+  ComponentStreamAdapter,
+  createComponentStreamAdapter,
+  hasToolCalls,
+  extractToolResults,
+  type DataStreamWriter,
+  type ArtifactToolCall,
+  type ArtifactToolResult,
+} from './component-stream';

package/src/streaming/sse.ts

@@ -0,0 +1,241 @@
+/**
+ * SSE (Server-Sent Events) streaming utilities
+ */
+
+import { SSE_HEADERS } from '../utils/constants';
+
+export interface SSEEvent {
+  event?: string;
+  data: unknown;
+  id?: string;
+  retry?: number;
+}
+
+/**
+ * Parse SSE stream from a Response
+ */
+export async function* parseSSEStream(
+  response: Response
+): AsyncIterable<SSEEvent> {
+  if (!response.body) {
+    throw new Error('Response body is null');
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let currentEvent: Partial<SSEEvent> = {};
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+
+      for (const line of lines) {
+        if (line === '') {
+          // Empty line means end of event
+          if (currentEvent.data !== undefined) {
+            yield currentEvent as SSEEvent;
+          }
+          currentEvent = {};
+          continue;
+        }
+
+        if (line.startsWith(':')) {
+          // Comment, skip
+          continue;
+        }
+
+        const colonIndex = line.indexOf(':');
+        if (colonIndex === -1) continue;
+
+        const field = line.slice(0, colonIndex);
+        const value = line.slice(colonIndex + 1).trimStart();
+
+        switch (field) {
+          case 'event':
+            currentEvent.event = value;
+            break;
+          case 'data':
+            try {
+              currentEvent.data = JSON.parse(value);
+            } catch {
+              currentEvent.data = value;
+            }
+            break;
+          case 'id':
+            currentEvent.id = value;
+            break;
+          case 'retry':
+            currentEvent.retry = parseInt(value, 10);
+            break;
+        }
+      }
+    }
+
+    // Emit any remaining event
+    if (currentEvent.data !== undefined) {
+      yield currentEvent as SSEEvent;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/**
+ * Create an SSE Response from an async iterable
+ */
+export function createSSEResponse(
+  stream: AsyncIterable<SSEEvent>,
+  headers?: Record<string, string>
+): Response {
+  const encoder = new TextEncoder();
+
+  const readableStream = new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const event of stream) {
+          let message = '';
+
+          if (event.event) {
+            message += `event: ${event.event}\n`;
+          }
+
+          if (event.id) {
+            message += `id: ${event.id}\n`;
+          }
+
+          if (event.retry) {
+            message += `retry: ${event.retry}\n`;
+          }
+
+          const data =
+            typeof event.data === 'string'
+              ? event.data
+              : JSON.stringify(event.data);
+
+          message += `data: ${data}\n\n`;
+
+          controller.enqueue(encoder.encode(message));
+        }
+      } catch (error) {
+        console.error('SSE stream error:', error);
+      } finally {
+        controller.close();
+      }
+    },
+  });
+
+  return new Response(readableStream, {
+    headers: {
+      ...SSE_HEADERS,
+      ...headers,
+    },
+  });
+}
+
+/**
+ * Create an SSE writer for streaming events
+ */
+export class SSEWriter {
+  private encoder = new TextEncoder();
+  private controller: ReadableStreamDefaultController<Uint8Array> | null = null;
+  private stream: ReadableStream<Uint8Array>;
+
+  constructor() {
+    this.stream = new ReadableStream({
+      start: (controller) => {
+        this.controller = controller;
+      },
+    });
+  }
+
+  /**
+   * Get the underlying ReadableStream
+   */
+  getStream(): ReadableStream<Uint8Array> {
+    return this.stream;
+  }
+
+  /**
+   * Get a Response object for this stream
+   */
+  getResponse(headers?: Record<string, string>): Response {
+    return new Response(this.stream, {
+      headers: {
+        ...SSE_HEADERS,
+        ...headers,
+      },
+    });
+  }
+
+  /**
+   * Write an SSE event
+   */
+  write(event: SSEEvent): void {
+    if (!this.controller) return;
+
+    let message = '';
+
+    if (event.event) {
+      message += `event: ${event.event}\n`;
+    }
+
+    if (event.id) {
+      message += `id: ${event.id}\n`;
+    }
+
+    const data =
+      typeof event.data === 'string' ? event.data : JSON.stringify(event.data);
+
+    message += `data: ${data}\n\n`;
+
+    this.controller.enqueue(this.encoder.encode(message));
+  }
+
+  /**
+   * Write a data-only event
+   */
+  writeData(data: unknown): void {
+    this.write({ data });
+  }
+
+  /**
+   * Write a comment (for keep-alive)
+   */
+  writeComment(comment: string): void {
+    if (!this.controller) return;
+    this.controller.enqueue(this.encoder.encode(`: ${comment}\n\n`));
+  }
+
+  /**
+   * Close the stream
+   */
+  close(): void {
+    if (this.controller) {
+      this.controller.close();
+      this.controller = null;
+    }
+  }
+
+  /**
+   * Signal an error
+   */
+  error(err: Error): void {
+    if (this.controller) {
+      this.controller.error(err);
+      this.controller = null;
+    }
+  }
+}
+
+/**
+ * Create an SSE writer
+ */
+export function createSSEWriter(): SSEWriter {
+  return new SSEWriter();
+}

package/src/types/agent.ts

@@ -0,0 +1,106 @@
+/**
+ * Agent type definitions
+ */
+
+export interface Agent {
+  id: string;
+  name: string;
+  description?: string;
+  system_prompt?: string;
+  model?: string;
+  tools?: string[];
+  triggers?: AgentTrigger[];
+  workflow?: AgentWorkflow;
+  visibility?: 'public' | 'private' | 'template';
+  creator_mid?: string;
+  created_at?: string;
+  updated_at?: string;
+  enabled?: boolean;
+}
+
+export interface AgentTrigger {
+  type: 'webhook' | 'cron' | 'event';
+  config: Record<string, unknown>;
+}
+
+export interface AgentWorkflow {
+  nodes: AgentWorkflowNode[];
+  edges: AgentWorkflowEdge[];
+}
+
+export interface AgentWorkflowNode {
+  id: string;
+  type: string;
+  position: { x: number; y: number };
+  data: Record<string, unknown>;
+}
+
+export interface AgentWorkflowEdge {
+  id: string;
+  source: string;
+  target: string;
+  sourceHandle?: string;
+  targetHandle?: string;
+}
+
+export interface AgentExecuteRequest {
+  input?: string;
+  context?: Record<string, unknown>;
+  stream?: boolean;
+}
+
+export interface AgentExecuteResponse {
+  id: string;
+  output: string;
+  status: 'success' | 'error';
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentsListResponse {
+  agents: Agent[];
+}
+
+export interface AgentResponse {
+  agent?: Agent;
+  id?: string;
+  name?: string;
+  error?: string;
+}
+
+export interface AgentCreateInput {
+  name: string;
+  description?: string;
+  system_prompt?: string;
+  model?: string;
+  tools?: string[];
+  triggers?: AgentTrigger[];
+  workflow?: AgentWorkflow;
+  visibility?: 'public' | 'private' | 'template';
+  created_by?: string;
+}
+
+export interface AgentUpdateInput {
+  name?: string;
+  description?: string;
+  system_prompt?: string;
+  model?: string;
+  tools?: string[];
+  triggers?: AgentTrigger[];
+  workflow?: AgentWorkflow;
+  visibility?: 'public' | 'private' | 'template';
+  enabled?: boolean;
+}
+
+export interface AgentFromPromptInput {
+  prompt: string;
+  created_by?: string;
+}
+
+export interface AgentsClientConfig {
+  baseUrl?: string;
+  /**
+   * Use the coprocessor API (/cpx/agent/agents) instead of legacy (/agents).
+   * Defaults to true. Set to false for backwards compatibility.
+   */
+  useCpxApi?: boolean;
+}