Implementing channels to be handled in wasm

wit/channel.wit

@@ -0,0 +1,276 @@
+// WASM Channel Sandbox Interface
+//
+// Defines the contract between sandboxed channels and the host runtime.
+// Channels export the `channel` interface; the host provides the `channel-host` interface.
+//
+// Architecture: Host-Managed Event Loop
+// ┌─────────────────────────────────────────────────────────────────────────────────┐
+// │                          Host-Managed Event Loop                                 │
+// │                                                                                  │
+// │   ┌─────────────┐     ┌──────────────┐     ┌──────────────┐                     │
+// │   │   HTTP      │     │   Polling    │     │   Timer      │                     │
+// │   │   Router    │     │   Scheduler  │     │   Scheduler  │                     │
+// │   └──────┬──────┘     └──────┬───────┘     └──────┬───────┘                     │
+// │          └───────────────────┴────────────────────┘                              │
+// │                              │                                                   │
+// │                              ▼                                                   │
+// │          ┌──────────────────┬──────────────────┐                                │
+// │          ▼                  ▼                  ▼                                 │
+// │   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐                           │
+// │   │ on-http-req │   │  on-poll    │   │ on-respond  │  WASM Exports             │
+// │   └─────────────┘   └─────────────┘   └─────────────┘                           │
+// │          │                  │                  │                                 │
+// │          └──────────────────┴──────────────────┘                                │
+// │                             │                                                    │
+// │                             ▼                                                    │
+// │                    ┌─────────────────┐                                           │
+// │                    │  Host Imports   │                                           │
+// │                    │  emit-message   │──────────▶ MessageStream                 │
+// │                    │  http-request   │                                           │
+// │                    └─────────────────┘                                           │
+// └─────────────────────────────────────────────────────────────────────────────────┘
+//
+// Security Model:
+// - WASM channels are untrusted and run in a sandbox
+// - Fresh instance per callback (no shared mutable state)
+// - All capabilities are opt-in (default: no access)
+// - Secrets are NEVER exposed to WASM; credentials are injected at host boundary
+// - Workspace writes are prefixed with channels/<name>/ to prevent escape
+// - Message emission is rate-limited
+
+package near:agent;
+
+/// Host-provided capabilities for sandboxed channels.
+///
+/// Extends base tool capabilities with channel-specific functions:
+/// - emit-message: Queue messages for delivery to the agent
+/// - workspace-write: Write to channel-namespaced workspace
+interface channel-host {
+    // ==================== Base Capabilities (from tool host) ====================
+
+    /// Log levels for structured logging.
+    enum log-level {
+        trace,
+        debug,
+        info,
+        warn,
+        error,
+    }
+
+    /// Emit a log message.
+    ///
+    /// Messages are collected and emitted after execution completes.
+    /// Rate-limited to 1000 entries per execution, 4KB per message.
+    log: func(level: log-level, message: string);
+
+    /// Get the current timestamp in milliseconds since Unix epoch.
+    now-millis: func() -> u64;
+
+    /// Read a file from the workspace.
+    ///
+    /// Path is automatically prefixed with channels/<name>/.
+    /// Path must be relative (no leading /) and cannot contain "..".
+    /// Returns None if the file doesn't exist.
+    workspace-read: func(path: string) -> option<string>;
+
+    /// Response from an HTTP request.
+    record http-response {
+        /// HTTP status code.
+        status: u16,
+        /// Response headers as JSON object string.
+        headers-json: string,
+        /// Response body bytes.
+        body: list<u8>,
+    }
+
+    /// Make an HTTP request (if capability granted).
+    ///
+    /// Security:
+    /// - Only allowed endpoints (host/path patterns) can be accessed
+    /// - Credentials are injected by the host; WASM never sees them
+    /// - Response is scanned for leaked secrets before returning
+    /// - Rate-limited per channel
+    http-request: func(
+        method: string,
+        url: string,
+        headers-json: string,
+        body: option<list<u8>>
+    ) -> result<http-response, string>;
+
+    /// Check if a secret exists (if capability granted).
+    ///
+    /// Security:
+    /// - WASM can only check existence, NEVER read values
+    /// - Only allowed secret names can be checked
+    /// - Actual credentials are injected by host during HTTP requests
+    secret-exists: func(name: string) -> bool;
+
+    // ==================== Channel-Specific Capabilities ====================
+
+    /// A message to emit to the agent.
+    record emitted-message {
+        /// User identifier within the channel (e.g., Slack user ID).
+        user-id: string,
+        /// Optional human-readable user name.
+        user-name: option<string>,
+        /// Message content.
+        content: string,
+        /// Optional thread ID for threaded conversations.
+        thread-id: option<string>,
+        /// Channel-specific metadata as JSON string.
+        metadata-json: string,
+    }
+
+    /// Emit a message to the agent.
+    ///
+    /// Messages are queued during callback execution and delivered after
+    /// the callback completes successfully.
+    ///
+    /// Security:
+    /// - Rate-limited per execution (max 100 messages)
+    /// - Rate-limited globally per channel (configurable)
+    /// - Content size limited to 64KB
+    emit-message: func(msg: emitted-message);
+
+    /// Write a file to the workspace.
+    ///
+    /// Path is automatically prefixed with channels/<name>/.
+    /// Path must be relative (no leading /) and cannot contain "..".
+    ///
+    /// Returns Err if:
+    /// - Path validation fails (traversal attempt, absolute path)
+    /// - Write operation fails
+    workspace-write: func(path: string, content: string) -> result<_, string>;
+}
+
+/// Channel interface that sandboxed channels must implement.
+interface channel {
+    // ==================== Configuration Types ====================
+
+    /// Configuration for an HTTP endpoint.
+    record http-endpoint-config {
+        /// Path to register (e.g., "/webhook/slack").
+        path: string,
+        /// Allowed HTTP methods (e.g., ["POST"]).
+        methods: list<string>,
+        /// Whether the endpoint requires secret validation.
+        require-secret: bool,
+    }
+
+    /// Configuration for polling behavior.
+    record poll-config {
+        /// Polling interval in milliseconds (minimum 30000).
+        interval-ms: u32,
+        /// Whether polling is enabled.
+        enabled: bool,
+    }
+
+    /// Channel configuration returned by on-start.
+    record channel-config {
+        /// Human-readable display name.
+        display-name: string,
+        /// HTTP endpoints to register.
+        http-endpoints: list<http-endpoint-config>,
+        /// Optional polling configuration.
+        poll: option<poll-config>,
+    }
+
+    // ==================== Request/Response Types ====================
+
+    /// Incoming HTTP request from a webhook.
+    record incoming-http-request {
+        /// HTTP method (GET, POST, etc.).
+        method: string,
+        /// Request path.
+        path: string,
+        /// Request headers as JSON object string.
+        headers-json: string,
+        /// Query parameters as JSON object string.
+        query-json: string,
+        /// Request body bytes.
+        body: list<u8>,
+        /// Whether the webhook secret was validated by the host.
+        secret-validated: bool,
+    }
+
+    /// HTTP response to return to the webhook caller.
+    record outgoing-http-response {
+        /// HTTP status code.
+        status: u16,
+        /// Response headers as JSON object string.
+        headers-json: string,
+        /// Response body bytes.
+        body: list<u8>,
+    }
+
+    /// Agent response to be sent back to the channel.
+    record agent-response {
+        /// Unique message ID for correlation.
+        message-id: string,
+        /// Response content from the agent.
+        content: string,
+        /// Optional thread ID for threaded replies.
+        thread-id: option<string>,
+        /// Channel-specific metadata as JSON string.
+        metadata-json: string,
+    }
+
+    // ==================== Lifecycle Callbacks ====================
+
+    /// Initialize the channel.
+    ///
+    /// Called once when the channel is loaded. Returns configuration
+    /// describing HTTP endpoints and polling behavior.
+    ///
+    /// Arguments:
+    /// - config-json: Channel configuration from the capabilities file.
+    ///
+    /// Returns:
+    /// - Ok(channel-config): Configuration for the host to set up routing
+    /// - Err(string): Initialization failure message
+    on-start: func(config-json: string) -> result<channel-config, string>;
+
+    /// Handle an incoming HTTP request.
+    ///
+    /// Called for each HTTP request to a registered endpoint.
+    /// Use emit-message to queue messages for the agent.
+    ///
+    /// Arguments:
+    /// - req: The incoming HTTP request
+    ///
+    /// Returns:
+    /// - HTTP response to send back to the caller
+    on-http-request: func(req: incoming-http-request) -> outgoing-http-response;
+
+    /// Handle a polling tick.
+    ///
+    /// Called periodically if polling is configured.
+    /// Use emit-message to queue messages discovered during polling.
+    on-poll: func();
+
+    /// Deliver an agent response to the channel.
+    ///
+    /// Called when the agent has generated a response to a message
+    /// that was emitted by this channel.
+    ///
+    /// Arguments:
+    /// - response: The agent's response
+    ///
+    /// Returns:
+    /// - Ok: Response delivered successfully
+    /// - Err(string): Delivery failure message
+    on-respond: func(response: agent-response) -> result<_, string>;
+
+    /// Clean up channel resources.
+    ///
+    /// Called when the channel is being unloaded.
+    on-shutdown: func();
+}
+
+/// World definition for sandboxed channels.
+///
+/// Channels import host capabilities and export the channel interface.
+world sandboxed-channel {
+    import channel-host;
+    export channel;
+}