@astropods/messaging 0.0.0

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './messaging-client';

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./messaging-client"), exports);

package/dist/messaging-client.d.ts

@@ -0,0 +1,232 @@
+import { EventEmitter } from 'events';
+export interface Message {
+    id?: string;
+    timestamp?: any;
+    platform: string;
+    platformContext?: PlatformContext;
+    user: User;
+    content: string;
+    attachments?: Attachment[];
+    conversationId: string;
+}
+export interface User {
+    id: string;
+    username?: string;
+    email?: string;
+    avatarUrl?: string;
+    userData?: {
+        [key: string]: string;
+    };
+}
+export interface PlatformContext {
+    messageId: string;
+    channelId: string;
+    threadId?: string;
+    channelName?: string;
+    workspaceId?: string;
+    platformData?: {
+        [key: string]: string;
+    };
+}
+export interface Attachment {
+    type: string;
+    url?: string;
+    filename?: string;
+    mimeType?: string;
+    title?: string;
+}
+export interface AgentResponse {
+    conversationId: string;
+    responseId?: string;
+    incomingMessage?: Message;
+    status?: StatusUpdate;
+    content?: ContentChunk;
+    prompts?: SuggestedPrompts;
+    threadMetadata?: ThreadMetadata;
+    error?: ErrorResponse;
+    contextRequest?: ThreadHistoryRequest;
+}
+export interface StatusUpdate {
+    status: 'THINKING' | 'SEARCHING' | 'GENERATING' | 'PROCESSING' | 'ANALYZING' | 'CUSTOM';
+    customMessage?: string;
+    emoji?: string;
+}
+export interface ContentChunk {
+    type: 'START' | 'DELTA' | 'END' | 'REPLACE';
+    content: string;
+    attachments?: any[];
+    platformMessageId?: string;
+    options?: any;
+}
+export interface SuggestedPrompts {
+    prompts: Array<{
+        id: string;
+        title: string;
+        message: string;
+        description?: string;
+    }>;
+}
+export interface ThreadMetadata {
+    threadId?: string;
+    title?: string;
+    createNew?: boolean;
+}
+export interface ErrorResponse {
+    code: string;
+    message: string;
+    details?: string;
+    retryable?: boolean;
+}
+export interface ThreadHistoryRequest {
+    conversationId: string;
+    maxMessages?: number;
+    includeEdited?: boolean;
+    includeDeleted?: boolean;
+}
+export interface ThreadHistoryResponse {
+    conversationId: string;
+    messages: ThreadMessage[];
+    isComplete: boolean;
+    fetchedAt?: any;
+}
+export interface ThreadMessage {
+    messageId: string;
+    user: User;
+    content: string;
+    attachments?: Attachment[];
+    timestamp: any;
+    wasEdited?: boolean;
+    isDeleted?: boolean;
+    originalContent?: string;
+    editedAt?: any;
+    deletedAt?: any;
+    platformData?: {
+        [key: string]: string;
+    };
+}
+export interface AgentToolGraphNode {
+    id: string;
+    name: string;
+    type: string;
+}
+export interface AgentToolGraphEdge {
+    id: string;
+    source: string;
+    target: string;
+}
+export interface AgentToolGraph {
+    nodes: AgentToolGraphNode[];
+    edges: AgentToolGraphEdge[];
+}
+export interface AgentToolConfig {
+    name: string;
+    title: string;
+    description: string;
+    type: string;
+    graph?: AgentToolGraph;
+}
+export interface AgentConfig {
+    systemPrompt: string;
+    tools: AgentToolConfig[];
+}
+export interface ConversationRequest {
+    message?: Message;
+    feedback?: any;
+    agentConfig?: AgentConfig;
+    agentResponse?: AgentResponse;
+}
+/**
+ * MessagingClient provides a TypeScript interface to the Astro Messaging gRPC service
+ */
+export declare class MessagingClient extends EventEmitter {
+    private serverAddress;
+    private client;
+    private conversationStream;
+    private isConnected;
+    constructor(serverAddress: string);
+    /**
+     * Connect to the gRPC server
+     */
+    connect(): Promise<void>;
+    /**
+     * Create a bidirectional conversation stream
+     */
+    createConversationStream(): ConversationStream;
+    /**
+     * Process a single message (server-side streaming)
+     */
+    processMessage(message: Message): Promise<MessageStream>;
+    /**
+     * Get thread history for a conversation
+     */
+    getThreadHistory(conversationId: string, maxMessages?: number): Promise<ThreadHistoryResponse>;
+    /**
+     * Get conversation metadata
+     */
+    getConversationMetadata(conversationId: string): Promise<any>;
+    /**
+     * Check service health
+     */
+    healthCheck(): Promise<{
+        status: string;
+    }>;
+    /**
+     * Close the client connection
+     */
+    close(): void;
+}
+/**
+ * ConversationStream wraps a bidirectional gRPC stream
+ */
+export declare class ConversationStream extends EventEmitter {
+    private stream;
+    constructor(stream: any);
+    /**
+     * Send a message through the stream
+     */
+    sendMessage(message: Message): void;
+    /**
+     * Send platform feedback through the stream
+     */
+    sendFeedback(feedback: any): void;
+    /**
+     * Send agent configuration through the stream
+     */
+    sendAgentConfig(config: AgentConfig): void;
+    /**
+     * Send a typed AgentResponse through the stream
+     */
+    sendAgentResponse(response: AgentResponse): void;
+    /**
+     * Send a content chunk (START/DELTA/END) for a conversation
+     */
+    sendContentChunk(conversationId: string, chunk: ContentChunk): void;
+    /**
+     * Send a status update for a conversation
+     */
+    sendStatusUpdate(conversationId: string, status: StatusUpdate): void;
+    /**
+     * End the stream
+     */
+    end(): void;
+}
+/**
+ * MessageStream wraps a server-side streaming response
+ */
+export declare class MessageStream extends EventEmitter {
+    private call;
+    constructor(call: any);
+}
+/**
+ * Helper functions for creating common message types
+ */
+export declare const Helpers: {
+    createMessage(conversationId: string, userId: string, username: string, content: string): Message;
+    createStatusResponse(conversationId: string, status: StatusUpdate["status"], message?: string): AgentResponse;
+    createContentResponse(conversationId: string, content: string, final?: boolean): AgentResponse;
+    createSuggestedPromptsResponse(conversationId: string, prompts: Array<{
+        title: string;
+        message: string;
+    }>): AgentResponse;
+    createErrorResponse(conversationId: string, code: string, message: string): AgentResponse;
+};

package/dist/messaging-client.js

@@ -0,0 +1,323 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Helpers = exports.MessageStream = exports.ConversationStream = exports.MessagingClient = void 0;
+const grpc = __importStar(require("@grpc/grpc-js"));
+const protoLoader = __importStar(require("@grpc/proto-loader"));
+const path_1 = require("path");
+const events_1 = require("events");
+/**
+ * MessagingClient provides a TypeScript interface to the Astro Messaging gRPC service
+ */
+class MessagingClient extends events_1.EventEmitter {
+    constructor(serverAddress) {
+        super();
+        this.serverAddress = serverAddress;
+        this.isConnected = false;
+    }
+    /**
+     * Connect to the gRPC server
+     */
+    async connect() {
+        const protoPath = 'astro/messaging/v1/service.proto';
+        const packageDefinition = protoLoader.loadSync(protoPath, {
+            keepCase: false,
+            longs: String,
+            enums: String,
+            defaults: true,
+            oneofs: true,
+            includeDirs: [(0, path_1.join)(__dirname, 'proto')],
+        });
+        const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
+        const AgentMessaging = protoDescriptor.astro.messaging.v1.AgentMessaging;
+        this.client = new AgentMessaging(this.serverAddress, grpc.credentials.createInsecure());
+        this.isConnected = true;
+        this.emit('connected');
+    }
+    /**
+     * Create a bidirectional conversation stream
+     */
+    createConversationStream() {
+        if (!this.isConnected) {
+            throw new Error('Client not connected. Call connect() first.');
+        }
+        this.conversationStream = this.client.ProcessConversation();
+        return new ConversationStream(this.conversationStream);
+    }
+    /**
+     * Process a single message (server-side streaming)
+     */
+    async processMessage(message) {
+        if (!this.isConnected) {
+            throw new Error('Client not connected. Call connect() first.');
+        }
+        return new Promise((resolve, reject) => {
+            const call = this.client.ProcessMessage(message);
+            resolve(new MessageStream(call));
+        });
+    }
+    /**
+     * Get thread history for a conversation
+     */
+    async getThreadHistory(conversationId, maxMessages = 50) {
+        if (!this.isConnected) {
+            throw new Error('Client not connected. Call connect() first.');
+        }
+        const request = {
+            conversationId,
+            maxMessages,
+            includeEdited: true,
+            includeDeleted: false,
+        };
+        return new Promise((resolve, reject) => {
+            this.client.GetThreadHistory(request, (error, response) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve(response);
+                }
+            });
+        });
+    }
+    /**
+     * Get conversation metadata
+     */
+    async getConversationMetadata(conversationId) {
+        if (!this.isConnected) {
+            throw new Error('Client not connected. Call connect() first.');
+        }
+        const request = {
+            identifier: {
+                conversationId,
+            },
+        };
+        return new Promise((resolve, reject) => {
+            this.client.GetConversationMetadata(request, (error, response) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve(response);
+                }
+            });
+        });
+    }
+    /**
+     * Check service health
+     */
+    async healthCheck() {
+        if (!this.isConnected) {
+            throw new Error('Client not connected. Call connect() first.');
+        }
+        return new Promise((resolve, reject) => {
+            this.client.HealthCheck({}, (error, response) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve(response);
+                }
+            });
+        });
+    }
+    /**
+     * Close the client connection
+     */
+    close() {
+        if (this.conversationStream) {
+            this.conversationStream.end();
+        }
+        if (this.client) {
+            this.client.close();
+        }
+        this.isConnected = false;
+        this.emit('disconnected');
+    }
+}
+exports.MessagingClient = MessagingClient;
+/**
+ * ConversationStream wraps a bidirectional gRPC stream
+ */
+class ConversationStream extends events_1.EventEmitter {
+    constructor(stream) {
+        super();
+        this.stream = stream;
+        this.stream.on('data', (response) => {
+            this.emit('response', response);
+        });
+        this.stream.on('end', () => {
+            this.emit('end');
+        });
+        this.stream.on('error', (error) => {
+            this.emit('error', error);
+        });
+    }
+    /**
+     * Send a message through the stream
+     */
+    sendMessage(message) {
+        const request = {
+            message,
+        };
+        this.stream.write(request);
+    }
+    /**
+     * Send platform feedback through the stream
+     */
+    sendFeedback(feedback) {
+        const request = {
+            feedback,
+        };
+        this.stream.write(request);
+    }
+    /**
+     * Send agent configuration through the stream
+     */
+    sendAgentConfig(config) {
+        const request = {
+            agentConfig: config,
+        };
+        this.stream.write(request);
+    }
+    /**
+     * Send a typed AgentResponse through the stream
+     */
+    sendAgentResponse(response) {
+        const request = {
+            agentResponse: response,
+        };
+        this.stream.write(request);
+    }
+    /**
+     * Send a content chunk (START/DELTA/END) for a conversation
+     */
+    sendContentChunk(conversationId, chunk) {
+        this.sendAgentResponse({
+            conversationId,
+            content: chunk,
+        });
+    }
+    /**
+     * Send a status update for a conversation
+     */
+    sendStatusUpdate(conversationId, status) {
+        this.sendAgentResponse({
+            conversationId,
+            status,
+        });
+    }
+    /**
+     * End the stream
+     */
+    end() {
+        this.stream.end();
+    }
+}
+exports.ConversationStream = ConversationStream;
+/**
+ * MessageStream wraps a server-side streaming response
+ */
+class MessageStream extends events_1.EventEmitter {
+    constructor(call) {
+        super();
+        this.call = call;
+        this.call.on('data', (response) => {
+            this.emit('response', response);
+        });
+        this.call.on('end', () => {
+            this.emit('end');
+        });
+        this.call.on('error', (error) => {
+            this.emit('error', error);
+        });
+    }
+}
+exports.MessageStream = MessageStream;
+/**
+ * Helper functions for creating common message types
+ */
+exports.Helpers = {
+    createMessage(conversationId, userId, username, content) {
+        return {
+            conversationId,
+            user: {
+                id: userId,
+                username,
+            },
+            content,
+            platform: 'slack',
+        };
+    },
+    createStatusResponse(conversationId, status, message) {
+        return {
+            conversationId,
+            status: {
+                status,
+                customMessage: message,
+            },
+        };
+    },
+    createContentResponse(conversationId, content, final = true) {
+        return {
+            conversationId,
+            content: {
+                type: final ? 'END' : 'START',
+                content,
+            },
+        };
+    },
+    createSuggestedPromptsResponse(conversationId, prompts) {
+        return {
+            conversationId,
+            prompts: {
+                prompts: prompts.map((p, i) => ({
+                    id: `prompt_${i}`,
+                    title: p.title,
+                    message: p.message,
+                })),
+            },
+        };
+    },
+    createErrorResponse(conversationId, code, message) {
+        return {
+            conversationId,
+            error: {
+                code,
+                message,
+            },
+        };
+    },
+};

package/dist/proto/astro/messaging/v1/config.proto

@@ -0,0 +1,38 @@
+syntax = "proto3";
+
+package astro.messaging.v1;
+
+option go_package = "github.com/postman/astro/messaging/v1;messagingv1";
+
+// Agent configuration declared at startup
+message AgentConfig {
+  string system_prompt = 1;
+  repeated AgentToolConfig tools = 2;
+}
+
+// Tool configuration for any agent
+message AgentToolConfig {
+  string name = 1;
+  string title = 2;
+  string description = 3;
+  string type = 4;                        // "graph" | "other"
+  AgentToolGraph graph = 5;               // Optional, present when type = "graph"
+}
+
+// Graph visualization for tool workflows
+message AgentToolGraph {
+  repeated AgentToolGraphNode nodes = 1;
+  repeated AgentToolGraphEdge edges = 2;
+}
+
+message AgentToolGraphNode {
+  string id = 1;
+  string name = 2;
+  string type = 3;
+}
+
+message AgentToolGraphEdge {
+  string id = 1;
+  string source = 2;
+  string target = 3;
+}

package/dist/proto/astro/messaging/v1/feedback.proto

@@ -0,0 +1,79 @@
+syntax = "proto3";
+
+package astro.messaging.v1;
+
+import "google/protobuf/timestamp.proto";
+
+option go_package = "github.com/postman/astro/messaging/v1;messagingv1";
+
+// Feedback from user interactions (platform → agent)
+// Used in bidirectional streaming for real-time agent updates
+message PlatformFeedback {
+  string conversation_id = 1;
+  string response_id = 2;                 // Which agent message this relates to (optional)
+  google.protobuf.Timestamp timestamp = 3;
+
+  oneof feedback {
+    StreamControl stream_control = 4;     // Stop/pause generation
+    PromptSelection prompt_selection = 5; // User clicked suggested prompt
+    MessageReaction reaction = 6;         // Thumbs up/down, emoji reaction
+    ButtonClick button_click = 7;         // Interactive button clicked
+    MessageEdit message_edit = 8;         // User edited a message
+    MessageDelete message_delete = 9;     // User deleted a message
+  }
+}
+
+// Control agent streaming/generation
+message StreamControl {
+  enum Action {
+    ACTION_UNSPECIFIED = 0;
+    STOP = 1;                             // Stop generating
+    PAUSE = 2;                            // Pause (resume later)
+    RESUME = 3;                           // Resume paused generation
+    REGENERATE = 4;                       // Regenerate last response
+  }
+
+  Action action = 1;
+  string reason = 2;                      // Why stopped (user click, error, etc.) (optional)
+}
+
+// User selected a suggested prompt
+message PromptSelection {
+  string prompt_id = 1;                   // Matches SuggestedPrompts.Prompt.id
+  string prompt_message = 2;              // Full message being sent
+}
+
+// User reacted to agent message
+message MessageReaction {
+  enum ReactionType {
+    REACTION_TYPE_UNSPECIFIED = 0;
+    THUMBS_UP = 1;
+    THUMBS_DOWN = 2;
+    CUSTOM_EMOJI = 3;
+  }
+
+  ReactionType type = 1;
+  string emoji = 2;                       // For CUSTOM_EMOJI (optional)
+  bool added = 3;                         // true = added, false = removed
+}
+
+// User clicked interactive button (from CardAttachment)
+message ButtonClick {
+  string button_id = 1;                   // Button identifier from card
+  string value = 2;                       // Button value/payload (optional)
+  string action = 3;                      // Action identifier
+}
+
+// User edited a previous message
+message MessageEdit {
+  string message_id = 1;                  // Platform message ID that was edited
+  string new_content = 2;                 // New content after edit
+  string original_content = 3;            // Original content (if available) (optional)
+  google.protobuf.Timestamp edited_at = 4;
+}
+
+// User deleted a previous message
+message MessageDelete {
+  string message_id = 1;                  // Platform message ID that was deleted
+  google.protobuf.Timestamp deleted_at = 2;
+}

package/dist/proto/astro/messaging/v1/message.proto

@@ -0,0 +1,81 @@
+syntax = "proto3";
+
+package astro.messaging.v1;
+
+import "google/protobuf/timestamp.proto";
+
+option go_package = "github.com/postman/astro/messaging/v1;messagingv1";
+
+// Message from user to agent (platform → agent)
+message Message {
+  // Identity (who, when, where)
+  string id = 1;                          // UUID generated by messaging service
+  google.protobuf.Timestamp timestamp = 2;
+
+  // Platform identification
+  string platform = 3;                    // "slack" | "discord" | "teams"
+  PlatformContext platform_context = 4;   // Platform-specific IDs and metadata
+
+  // User who sent the message
+  User user = 5;
+
+  // Message content
+  string content = 6;                     // Cleaned text (mentions resolved, etc.)
+  repeated Attachment attachments = 7;
+
+  // Conversation routing
+  // Messaging service provides this for correlation only
+  // Agent is responsible for loading/storing actual conversation history
+  string conversation_id = 8;             // Stable ID across message lifecycle
+}
+
+// Platform-specific context (adapter populates this)
+message PlatformContext {
+  // Required: Core platform IDs
+  string message_id = 1;                  // Original platform message ID
+  string channel_id = 2;                  // Channel/room/chat ID
+  string thread_id = 3;                   // Thread/reply chain ID (optional)
+
+  // Optional: Display names
+  string channel_name = 4;
+  string workspace_id = 5;                // Slack workspace, Discord guild, etc.
+
+  // Platform-specific data
+  // Examples: Slack ts, Discord snowflake, Teams activity ID
+  map<string, string> platform_data = 10;
+}
+
+// User information
+message User {
+  string id = 1;                          // Platform-specific user ID
+  string username = 2;                    // Display name or handle
+  string avatar_url = 3;                  // Avatar URL (optional)
+  string email = 4;                       // Email if available (optional)
+
+  // Platform-specific user data
+  map<string, string> user_data = 5;
+}
+
+// Attachment from user message
+message Attachment {
+  enum Type {
+    TYPE_UNSPECIFIED = 0;
+    IMAGE = 1;                            // jpg, png, gif, webp
+    FILE = 2;                             // Generic file
+    VIDEO = 3;                            // mp4, mov, etc.
+    AUDIO = 4;                            // mp3, wav, etc.
+    LINK = 5;                             // URL preview/embed
+  }
+
+  Type type = 1;
+  string url = 2;                         // Direct download URL (authenticated)
+  string filename = 3;
+  int64 size_bytes = 4;                   // Optional
+  string mime_type = 5;                   // Optional
+
+  // Optional metadata for rich attachments
+  string title = 6;
+  string description = 7;
+  int32 width = 8;                        // For images/videos
+  int32 height = 9;
+}

package/dist/proto/astro/messaging/v1/response.proto

@@ -0,0 +1,198 @@
+syntax = "proto3";
+
+package astro.messaging.v1;
+
+import "google/protobuf/timestamp.proto";
+import "astro/messaging/v1/message.proto";
+
+option go_package = "github.com/postman/astro/messaging/v1;messagingv1";
+
+// Agent's streamed response (agent → platform)
+// Agent can send multiple AgentResponse messages in a stream
+// Also used by server to send incoming platform messages to agent
+message AgentResponse {
+  string conversation_id = 1;             // Matches incoming Message.conversation_id
+  string response_id = 2;                 // Stable ID for this response (for updates)
+
+  oneof payload {
+    Message incoming_message = 3;         // Incoming platform message (server → agent)
+    StatusUpdate status = 4;              // "Thinking...", typing indicator
+    ContentChunk content = 5;             // Actual message content (streamed)
+    SuggestedPrompts prompts = 6;         // Quick reply suggestions
+    ThreadMetadata thread_metadata = 7;   // Thread title, creation
+    ErrorResponse error = 8;              // Error during processing
+    ThreadHistoryRequest context_request = 9;  // Request cached context (optional)
+  }
+}
+
+// AI status indicators (loading states, typing)
+// Platform translation:
+// - Slack: assistant.threads.setStatus
+// - Discord: typing indicator via bot.send_typing()
+// - Teams: typing indicator via sendTypingIndicator()
+message StatusUpdate {
+  enum Status {
+    STATUS_UNSPECIFIED = 0;
+    THINKING = 1;                         // Generic "thinking"
+    SEARCHING = 2;                        // RAG/knowledge base search
+    GENERATING = 3;                       // LLM generation in progress
+    PROCESSING = 4;                       // Tool execution
+    ANALYZING = 5;                        // Data analysis
+    CUSTOM = 10;                          // Custom status with message
+  }
+
+  Status status = 1;
+  string custom_message = 2;              // Used with CUSTOM or overrides default (optional)
+  string emoji = 3;                       // Platform emoji (e.g., ":robot_face:") (optional)
+}
+
+// Streamed message content
+// Flow: START → DELTA(s) → END (or just START for complete message)
+message ContentChunk {
+  enum ChunkType {
+    CHUNK_TYPE_UNSPECIFIED = 0;
+    START = 1;                            // Create message, returns platform message_id
+    DELTA = 2;                            // Append/update content (streamed tokens)
+    END = 3;                              // Finalize message
+    REPLACE = 4;                          // Full content replacement (edit)
+  }
+
+  ChunkType type = 1;
+
+  // Content handling based on type:
+  // START: Full initial content (may be empty for immediate presence)
+  // DELTA: Incremental text to append (LLM tokens)
+  // END: Final text (if any last content) + attachments
+  // REPLACE: Complete new content (overwrites existing)
+  string content = 2;
+
+  // Attachments sent with END chunk or standalone
+  repeated ResponseAttachment attachments = 3;
+
+  // Platform message ID (returned after START, used for updates)
+  string platform_message_id = 4;         // Optional
+
+  // Options for message creation
+  MessageOptions options = 5;             // Optional
+}
+
+// Attachments in agent responses (richer than user attachments)
+message ResponseAttachment {
+  oneof attachment_type {
+    ImageAttachment image = 1;
+    FileAttachment file = 2;
+    CardAttachment card = 3;             // Rich cards (Slack blocks, Teams adaptive cards)
+    LinkPreview link = 4;
+  }
+}
+
+message ImageAttachment {
+  string url = 1;                         // Public URL or data URI
+  string alt_text = 2;                    // Optional
+  string title = 3;                       // Optional
+  int32 width = 4;                        // Optional
+  int32 height = 5;                       // Optional
+}
+
+message FileAttachment {
+  string url = 1;
+  string filename = 2;
+  string mime_type = 3;                   // Optional
+  int64 size_bytes = 4;                   // Optional
+}
+
+message CardAttachment {
+  string platform_card_json = 1;          // Platform-specific JSON
+  // Adapters translate: Slack Block Kit, Discord Embeds, Teams Adaptive Cards
+}
+
+message LinkPreview {
+  string url = 1;
+  string title = 2;                       // Optional
+  string description = 3;                 // Optional
+  string image_url = 4;                   // Optional
+}
+
+// Message creation options
+message MessageOptions {
+  bool ephemeral = 1;                     // Only visible to user
+  bool create_thread = 2;                 // Start new thread
+  string reply_to_message_id = 3;         // Reply to specific message (optional)
+  bool silent = 4;                        // No notification
+}
+
+// Suggested quick replies (Slack AI, Teams suggested actions)
+// Platform translation:
+// - Slack: assistant.threads.setSuggestedPrompts
+// - Teams: suggestedActions in bot response
+// - Discord: Custom buttons (component interactions)
+message SuggestedPrompts {
+  message Prompt {
+    string id = 1;                        // Unique ID (for tracking selection)
+    string title = 2;                     // Button/chip label
+    string message = 3;                   // Full message sent when selected
+    string description = 4;               // Tooltip/help text (optional)
+  }
+
+  repeated Prompt prompts = 1;            // Max 4-6 depending on platform
+}
+
+// Thread management (create, update title)
+message ThreadMetadata {
+  string thread_id = 1;                   // Platform thread ID (if updating) (optional)
+  string title = 2;                       // Thread title/subject (optional)
+  bool create_new = 3;                    // Create new thread
+}
+
+// Error response from agent
+message ErrorResponse {
+  enum ErrorCode {
+    ERROR_CODE_UNSPECIFIED = 0;
+    RATE_LIMIT = 1;                       // Agent hit rate limit
+    CONTEXT_TOO_LONG = 2;                 // Context exceeds LLM limit
+    INVALID_REQUEST = 3;                  // Malformed request
+    AGENT_ERROR = 4;                      // Internal agent error
+    TOOL_ERROR = 5;                       // Tool execution failed
+    PLATFORM_ERROR = 6;                   // Platform API error
+  }
+
+  ErrorCode code = 1;
+  string message = 2;                     // User-facing error message
+  string details = 3;                     // Technical details (logged, not shown) (optional)
+  bool retryable = 4;                     // Can user retry?
+}
+
+// Agent requests thread hydration from adapter
+message ThreadHistoryRequest {
+  string conversation_id = 1;
+  int32 max_messages = 2;                 // How many recent messages (default: 50)
+  bool include_edited = 3;                // Include edit history (default: true)
+  bool include_deleted = 4;               // Include deleted markers (default: false)
+}
+
+message ThreadHistoryResponse {
+  string conversation_id = 1;
+  repeated ThreadMessage messages = 2;
+  bool is_complete = 3;                   // False if truncated due to max_messages
+  google.protobuf.Timestamp fetched_at = 4;
+}
+
+message ThreadMessage {
+  string message_id = 1;                  // Platform message ID
+  User user = 2;
+  string content = 3;                     // Current content (after edits)
+  repeated Attachment attachments = 4;
+  google.protobuf.Timestamp timestamp = 5;
+
+  // Edit tracking
+  bool was_edited = 6;
+  string original_content = 7;            // Content before edits (optional)
+  google.protobuf.Timestamp edited_at = 8; // Optional
+
+  // Deletion tracking
+  bool is_deleted = 9;
+  google.protobuf.Timestamp deleted_at = 10; // Optional
+
+  // Platform-specific data
+  map<string, string> platform_data = 11;
+}

package/dist/proto/astro/messaging/v1/service.proto

@@ -0,0 +1,84 @@
+syntax = "proto3";
+
+package astro.messaging.v1;
+
+import "astro/messaging/v1/message.proto";
+import "astro/messaging/v1/response.proto";
+import "astro/messaging/v1/feedback.proto";
+import "astro/messaging/v1/config.proto";
+import "google/protobuf/timestamp.proto";
+
+option go_package = "github.com/postman/astro/messaging/v1;messagingv1";
+
+// Main gRPC service for agent messaging
+service AgentMessaging {
+  // Bidirectional streaming for real-time AI conversations
+  rpc ProcessConversation(stream ConversationRequest)
+      returns (stream AgentResponse);
+
+  // Server streaming for simple request/response with streaming reply
+  rpc ProcessMessage(Message)
+      returns (stream AgentResponse);
+
+  // Get current thread history from platform (handles edits/deletes)
+  // Agent calls this to hydrate accurate thread state
+  rpc GetThreadHistory(ThreadHistoryRequest)
+      returns (ThreadHistoryResponse);
+
+  // Optional: Query cache for conversation metadata (not full history)
+  rpc GetConversationMetadata(ConversationMetadataRequest)
+      returns (ConversationMetadataResponse);
+
+  // Health check
+  rpc HealthCheck(HealthCheckRequest)
+      returns (HealthCheckResponse);
+}
+
+// Request wrapper for bidirectional streaming
+message ConversationRequest {
+  oneof request {
+    Message message = 1;
+    PlatformFeedback feedback = 2;
+    AgentConfig agent_config = 3;
+    AgentResponse agent_response = 4;
+  }
+}
+
+// Conversation metadata (routing info, not full history)
+message ConversationMetadataRequest {
+  oneof identifier {
+    string conversation_id = 1;
+    PlatformIdentifier platform_id = 2;
+  }
+}
+
+message PlatformIdentifier {
+  string platform = 1;                    // "slack", "discord", "teams"
+  string channel_id = 2;
+  string thread_id = 3;                   // Optional
+}
+
+message ConversationMetadataResponse {
+  string conversation_id = 1;
+  string platform = 2;
+  string channel_id = 3;
+  string thread_id = 4;                   // Optional
+  google.protobuf.Timestamp last_message_time = 5;
+  int32 message_count = 6;                // Approximate from cache
+  bool found = 7;                         // Whether conversation exists in cache
+}
+
+// Health check
+message HealthCheckRequest {}
+
+message HealthCheckResponse {
+  enum Status {
+    UNKNOWN = 0;
+    HEALTHY = 1;
+    DEGRADED = 2;
+    UNHEALTHY = 3;
+  }
+
+  Status status = 1;
+  string version = 2;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@astropods/messaging",
+  "version": "0.0.0",
+  "description": "TypeScript SDK for Astro Messaging",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "postinstall": "ln -sfn ../../proto proto",
+    "build": "tsc && cp -r ../../proto dist/proto",
+    "watch": "tsc --watch",
+    "test": "bun test",
+    "test:watch": "bun test --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/astropods/messaging.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.9.0",
+    "@grpc/proto-loader": "^0.7.10"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0"
+  }
+}