@maincode-ai/channel-base 0.18.3

package/README.md

@@ -0,0 +1,295 @@
+# @maincode-ai/channel-base
+
+Base infrastructure for building Matilda Code channel adapters. Provides the abstract base class, access control, session routing, and the ACP bridge that communicates with the agent.
+
+If you're building a channel plugin, this is your only dependency.
+
+## Install
+
+```bash
+npm install @maincode-ai/channel-base
+```
+
+## Quick start
+
+Subclass `ChannelBase` and implement three methods:
+
+```typescript
+import { ChannelBase } from '@maincode-ai/channel-base';
+import type {
+  ChannelConfig,
+  Envelope,
+  AcpBridge,
+} from '@maincode-ai/channel-base';
+
+class MyChannel extends ChannelBase {
+  async connect(): Promise<void> {
+    // Connect to platform API, register message handlers.
+    // When a message arrives, build an Envelope and call:
+    //   this.handleInbound(envelope)
+  }
+
+  async sendMessage(chatId: string, text: string): Promise<void> {
+    // Deliver the agent's response to the platform.
+  }
+
+  disconnect(): void {
+    // Clean up connections on shutdown.
+  }
+}
+```
+
+Export a `ChannelPlugin` object so the extension loader can discover it:
+
+```typescript
+import type { ChannelPlugin } from '@maincode-ai/channel-base';
+
+export const plugin: ChannelPlugin = {
+  channelType: 'my-platform',
+  displayName: 'My Platform',
+  requiredConfigFields: ['apiKey'],
+  createChannel: (name, config, bridge, options) =>
+    new MyChannel(name, config, bridge, options),
+};
+```
+
+For a complete working example, see [`@matilda-code/channel-plugin-example`](../plugin-example/).
+
+## Architecture
+
+```
+Inbound:  Platform message
+            → Envelope (with attachments)
+            → GroupGate (group policy + mention gating)
+            → SenderGate (allowlist / pairing / open)
+            → Slash commands (/clear, /help, /status)
+            → SessionRouter (resolve or create ACP session)
+            → Resolve attachments (images → bridge, files → prompt text)
+            → AcpBridge.prompt() → agent
+
+Outbound: Agent response
+            → BlockStreamer (if enabled: split into blocks at paragraph boundaries)
+            → sendMessage() → platform
+```
+
+Everything between `handleInbound()` and `sendMessage()` is handled by the base class — your adapter only deals with platform I/O.
+
+## Exports
+
+### Classes
+
+| Class           | Purpose                                                             |
+| --------------- | ------------------------------------------------------------------- |
+| `ChannelBase`   | Abstract base class — extend this to build a channel adapter        |
+| `AcpBridge`     | Spawns and communicates with the `matilda-code --acp` agent process |
+| `BlockStreamer` | Progressive multi-message delivery for block streaming              |
+| `SessionRouter` | Maps senders to ACP sessions with configurable scoping              |
+| `SenderGate`    | DM access control (allowlist / pairing / open)                      |
+| `GroupGate`     | Group chat policy and @mention gating                               |
+| `PairingStore`  | Pairing code generation, approval, and allowlist persistence        |
+
+### Types
+
+| Type            | Description                                    |
+| --------------- | ---------------------------------------------- |
+| `Attachment`    | Structured file/image/audio/video attachment   |
+| `ChannelConfig` | Channel configuration from `settings.json`     |
+| `ChannelPlugin` | Plugin factory interface (what you export)     |
+| `Envelope`      | Normalized inbound message format              |
+| `SenderPolicy`  | `'allowlist' \| 'pairing' \| 'open'`           |
+| `GroupPolicy`   | `'disabled' \| 'allowlist' \| 'open'`          |
+| `SessionScope`  | `'user' \| 'thread' \| 'single'`               |
+| `GroupConfig`   | Per-group settings (e.g. `requireMention`)     |
+| `SessionTarget` | Maps a session back to its channel/sender/chat |
+
+## API reference
+
+### ChannelBase
+
+```typescript
+constructor(name: string, config: ChannelConfig, bridge: AcpBridge, options?: ChannelBaseOptions)
+```
+
+**Abstract methods** (you must implement):
+
+| Method          | Signature                                                                    |
+| --------------- | ---------------------------------------------------------------------------- |
+| `connect()`     | `() => Promise<void>` — Connect to the platform and start receiving messages |
+| `sendMessage()` | `(chatId: string, text: string) => Promise<void>` — Deliver agent response   |
+| `disconnect()`  | `() => void` — Clean up on shutdown                                          |
+
+**Provided methods:**
+
+| Method                                            | Description                                                                                                                       |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `handleInbound(envelope)`                         | Route an inbound message through the full pipeline (gate checks, commands, session, prompt). Call this from your message handler. |
+| `setBridge(bridge)`                               | Replace the ACP bridge after crash recovery                                                                                       |
+| `registerCommand(name, handler)`                  | Register a custom slash command (e.g. `/mycommand`)                                                                               |
+| `onToolCall(chatId, event)`                       | Hook called on agent tool invocations — override to show indicators                                                               |
+| `onResponseChunk(chatId, chunk, sessionId)`       | Hook called per streaming text chunk — override for progressive display (default: no-op)                                          |
+| `onResponseComplete(chatId, fullText, sessionId)` | Hook called when full response is ready — override to customize delivery (default: `sendMessage()`)                               |
+
+**Block streaming:** When `blockStreaming: "on"` is set in the channel config, the base class automatically splits the agent's streaming response into multiple messages at paragraph boundaries. See [Block Streaming](#block-streaming) below.
+
+**Built-in slash commands:** `/clear` (`/reset`, `/new`), `/help`, `/status`
+
+### AcpBridge
+
+Manages the `matilda-code --acp` child process and ACP sessions.
+
+```typescript
+constructor(options: { cliEntryPath: string; cwd: string; model?: string })
+```
+
+| Method                              | Description                                                                                                       |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `start()`                           | Spawn the agent process                                                                                           |
+| `stop()`                            | Kill the agent process                                                                                            |
+| `newSession(cwd)`                   | Create a new ACP session, returns `sessionId`                                                                     |
+| `loadSession(sessionId, cwd)`       | Restore an existing session                                                                                       |
+| `prompt(sessionId, text, options?)` | Send a message to the agent, returns the full response text. Supports optional `imageBase64` and `imageMimeType`. |
+| `isConnected`                       | Whether the agent process is alive                                                                                |
+
+**Events** (EventEmitter):
+
+| Event          | Payload                  | Description              |
+| -------------- | ------------------------ | ------------------------ |
+| `textChunk`    | `(sessionId, chunk)`     | Streaming response chunk |
+| `toolCall`     | `(event: ToolCallEvent)` | Agent invoked a tool     |
+| `disconnected` | `(code, signal)`         | Agent process exited     |
+
+### SessionRouter
+
+Maps senders to ACP sessions based on the configured scope.
+
+```typescript
+constructor(bridge: AcpBridge, defaultCwd: string, scope?: SessionScope, persistPath?: string)
+```
+
+**Routing keys by scope:**
+
+| Scope            | Key format                | Effect                                    |
+| ---------------- | ------------------------- | ----------------------------------------- |
+| `user` (default) | `channel:senderId:chatId` | Each user gets their own session per chat |
+| `thread`         | `channel:threadId`        | One session per thread                    |
+| `single`         | `channel:__single__`      | One shared session for the entire channel |
+
+| Method                                                    | Description                                                 |
+| --------------------------------------------------------- | ----------------------------------------------------------- |
+| `resolve(channelName, senderId, chatId, threadId?, cwd?)` | Get or create a session for the given sender                |
+| `removeSession(channelName, senderId, chatId?)`           | Remove session(s) — used by `/clear`                        |
+| `restoreSessions()`                                       | Reload sessions from disk after bridge restart              |
+| `clearAll()`                                              | Clear all sessions and delete persist file (clean shutdown) |
+
+### SenderGate
+
+```typescript
+constructor(policy: SenderPolicy, allowedUsers?: string[], pairingStore?: PairingStore)
+```
+
+| Method                         | Description                                                  |
+| ------------------------------ | ------------------------------------------------------------ |
+| `check(senderId, senderName?)` | Returns `{ allowed: boolean, pairingCode?: string \| null }` |
+
+**Policy behavior:**
+
+| Policy      | Behavior                                                                                                  |
+| ----------- | --------------------------------------------------------------------------------------------------------- |
+| `open`      | Everyone allowed                                                                                          |
+| `allowlist` | Only `allowedUsers` allowed                                                                               |
+| `pairing`   | Check allowlist, then approved pairings, then generate a pairing code (8-char, 1hr expiry, max 3 pending) |
+
+### GroupGate
+
+```typescript
+constructor(policy?: GroupPolicy, groups?: Record<string, GroupConfig>)
+```
+
+| Method            | Description                                                                                    |
+| ----------------- | ---------------------------------------------------------------------------------------------- |
+| `check(envelope)` | Returns `{ allowed: boolean, reason?: 'disabled' \| 'not_allowlisted' \| 'mention_required' }` |
+
+**Policy behavior:**
+
+| Policy      | Behavior                                 |
+| ----------- | ---------------------------------------- |
+| `disabled`  | All group messages rejected              |
+| `allowlist` | Only groups listed in config are allowed |
+| `open`      | All groups allowed                       |
+
+When `requireMention` is `true` (default), group messages are only processed if the bot is @mentioned or the message is a reply to the bot.
+
+### PairingStore
+
+```typescript
+constructor(channelName: string)
+```
+
+Persists pairing state to `~/.matilda/channels/{channelName}-pairing.json` and `{channelName}-allowlist.json`.
+
+| Method                                | Description                                                                                               |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `createRequest(senderId, senderName)` | Generate an 8-char pairing code (or return existing). Returns `null` if 3 pending requests already exist. |
+| `approve(code)`                       | Approve a pairing request, adds sender to allowlist. Returns the request or `null`.                       |
+| `isApproved(senderId)`                | Check if sender is in the approved allowlist                                                              |
+| `listPending()`                       | Get active (non-expired) pending requests                                                                 |
+
+## Envelope
+
+The normalized message format your adapter must construct:
+
+```typescript
+interface Envelope {
+  channelName: string; // your channel instance name
+  senderId: string; // stable, unique sender ID
+  senderName: string; // display name
+  chatId: string; // distinguishes DMs from groups
+  text: string; // message text (@mentions stripped)
+  messageId?: string; // platform message ID
+  threadId?: string; // for thread-scoped sessions
+  isGroup: boolean; // true for group chats
+  isMentioned: boolean; // true if bot was @mentioned
+  isReplyToBot: boolean; // true if replying to bot's message
+  referencedText?: string; // quoted message text
+  imageBase64?: string; // base64-encoded image (legacy — prefer attachments)
+  imageMimeType?: string; // e.g. 'image/jpeg' (legacy — prefer attachments)
+  attachments?: Attachment[]; // structured file/image/audio/video attachments
+}
+
+interface Attachment {
+  type: 'image' | 'file' | 'audio' | 'video';
+  data?: string; // base64-encoded data (images, small files)
+  filePath?: string; // absolute path to local file (large files)
+  mimeType: string; // e.g. 'application/pdf', 'image/jpeg'
+  fileName?: string; // original file name from the platform
+}
+```
+
+`handleInbound()` automatically resolves attachments: images with `data` are sent to the model as vision input, files with `filePath` get their path appended to the prompt text so the agent can read them with its tools.
+
+## Block Streaming
+
+When `blockStreaming: "on"` is set in a channel's config, the agent's response is delivered as multiple separate messages instead of one large wall of text. The `BlockStreamer` accumulates streaming chunks and emits completed blocks based on paragraph boundaries and size heuristics.
+
+**Config fields** (on `ChannelConfig`):
+
+| Field                    | Type                     | Default         | Description                                                                 |
+| ------------------------ | ------------------------ | --------------- | --------------------------------------------------------------------------- |
+| `blockStreaming`         | `'on' \| 'off'`          | `'off'`         | Enable/disable block streaming                                              |
+| `blockStreamingChunk`    | `{ minChars, maxChars }` | `{ 400, 1000 }` | `minChars`: don't emit until this size. `maxChars`: force-emit at this size |
+| `blockStreamingCoalesce` | `{ idleMs }`             | `{ 1500 }`      | Emit buffered text after this many ms of silence from the agent             |
+
+**How it works:**
+
+1. Text accumulates as the agent streams its response
+2. When the buffer reaches `minChars` and hits a paragraph break (`\n\n`), that block is sent as a separate message
+3. If the buffer reaches `maxChars` without a paragraph break, it force-splits at the best break point (newline > space)
+4. If the agent goes quiet for `idleMs`, the buffer is flushed (as long as it's past `minChars`)
+5. When the agent finishes, any remaining text is sent immediately regardless of `minChars`
+
+Block streaming and `onResponseChunk` work independently — plugins can override `onResponseChunk` for their own purposes while block streaming handles delivery.
+
+## Further reading
+
+- [Channel Plugin Developer Guide](../../docs/developers/channel-plugins.md)
+- [`@matilda-code/channel-plugin-example`](../plugin-example/) — working reference implementation

package/dist/AcpBridge.d.ts

@@ -0,0 +1,41 @@
+import { EventEmitter } from 'node:events';
+export interface AcpBridgeOptions {
+    cliEntryPath: string;
+    cwd: string;
+    model?: string;
+}
+export interface AvailableCommand {
+    name: string;
+    description: string;
+    input?: {
+        hint: string;
+    } | null;
+}
+export interface ToolCallEvent {
+    sessionId: string;
+    toolCallId: string;
+    kind: string;
+    title: string;
+    status: string;
+    rawInput?: Record<string, unknown>;
+}
+export declare class AcpBridge extends EventEmitter {
+    private child;
+    private connection;
+    private options;
+    private _availableCommands;
+    constructor(options: AcpBridgeOptions);
+    get availableCommands(): AvailableCommand[];
+    start(): Promise<void>;
+    newSession(cwd: string): Promise<string>;
+    loadSession(sessionId: string, cwd: string): Promise<string>;
+    prompt(sessionId: string, text: string, options?: {
+        imageBase64?: string;
+        imageMimeType?: string;
+    }): Promise<string>;
+    cancelSession(sessionId: string): Promise<void>;
+    stop(): void;
+    get isConnected(): boolean;
+    private handleSessionUpdate;
+    private ensureConnection;
+}

package/dist/AcpBridge.js

@@ -0,0 +1,174 @@
+import { spawn } from 'node:child_process';
+import { Readable, Writable } from 'node:stream';
+import { EventEmitter } from 'node:events';
+import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from '@agentclientprotocol/sdk';
+export class AcpBridge extends EventEmitter {
+    child = null;
+    connection = null;
+    options;
+    _availableCommands = [];
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    get availableCommands() {
+        return this._availableCommands;
+    }
+    async start() {
+        const { cliEntryPath, cwd } = this.options;
+        const args = [
+            ...process.execArgv.filter((a) => !/^--inspect(-brk)?($|=)/.test(a)),
+            cliEntryPath,
+            '--acp',
+        ];
+        if (this.options.model) {
+            args.push('--model', this.options.model);
+        }
+        this.child = spawn(process.execPath, args, {
+            cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env },
+            shell: false,
+        });
+        this.child.stderr?.on('data', (data) => {
+            const msg = data.toString().trim();
+            if (msg) {
+                process.stderr.write(`[AcpBridge] ${msg}\n`);
+            }
+        });
+        this.child.on('exit', (code, signal) => {
+            process.stderr.write(`[AcpBridge] Process exited (code=${code}, signal=${signal})\n`);
+            this.connection = null;
+            this.child = null;
+            this.emit('disconnected', code, signal);
+        });
+        // Give the process a moment to start
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        if (!this.child || this.child.killed) {
+            throw new Error('ACP process failed to start');
+        }
+        const stdout = Readable.toWeb(this.child.stdout);
+        const stdin = Writable.toWeb(this.child.stdin);
+        const stream = ndJsonStream(stdin, stdout);
+        this.connection = new ClientSideConnection(() => ({
+            sessionUpdate: (params) => {
+                this.handleSessionUpdate(params);
+                return Promise.resolve();
+            },
+            requestPermission: async (params) => {
+                // Auto-approve for now; Phase 5 will add interactive approval
+                const options = Array.isArray(params.options) ? params.options : [];
+                const optionId = options.find((o) => o.optionId === 'proceed_once')?.optionId ||
+                    options[0]?.optionId ||
+                    'proceed_once';
+                return { outcome: { outcome: 'selected', optionId } };
+            },
+            extNotification: async () => { },
+        }), stream);
+        await this.connection.initialize({
+            protocolVersion: PROTOCOL_VERSION,
+            clientCapabilities: {},
+        });
+    }
+    async newSession(cwd) {
+        const conn = this.ensureConnection();
+        const response = await conn.newSession({ cwd, mcpServers: [] });
+        return response.sessionId;
+    }
+    async loadSession(sessionId, cwd) {
+        const conn = this.ensureConnection();
+        const response = await conn.loadSession({
+            sessionId,
+            cwd,
+            mcpServers: [],
+        });
+        return response.sessionId;
+    }
+    async prompt(sessionId, text, options) {
+        const conn = this.ensureConnection();
+        const chunks = [];
+        const onChunk = (sid, chunk) => {
+            if (sid === sessionId)
+                chunks.push(chunk);
+        };
+        this.on('textChunk', onChunk);
+        const prompt = [];
+        if (options?.imageBase64 && options.imageMimeType) {
+            prompt.push({
+                type: 'image',
+                data: options.imageBase64,
+                mimeType: options.imageMimeType,
+            });
+        }
+        prompt.push({ type: 'text', text });
+        try {
+            await conn.prompt({
+                sessionId,
+                prompt: prompt,
+            });
+        }
+        finally {
+            this.off('textChunk', onChunk);
+        }
+        return chunks.join('');
+    }
+    async cancelSession(sessionId) {
+        const conn = this.ensureConnection();
+        await conn.cancel({ sessionId });
+    }
+    stop() {
+        if (this.child) {
+            this.child.kill();
+            this.child = null;
+        }
+        this.connection = null;
+    }
+    get isConnected() {
+        return (this.child !== null && !this.child.killed && this.child.exitCode === null);
+    }
+    handleSessionUpdate(params) {
+        const { sessionId } = params;
+        const update = params['update'];
+        if (!update)
+            return;
+        const type = update['sessionUpdate'];
+        switch (type) {
+            case 'agent_message_chunk': {
+                const content = update['content'];
+                if (content?.type === 'text' && content.text) {
+                    this.emit('textChunk', sessionId, content.text);
+                }
+                break;
+            }
+            case 'tool_call': {
+                const event = {
+                    sessionId,
+                    toolCallId: update['toolCallId'],
+                    kind: update['kind'] || '',
+                    title: update['title'] || '',
+                    status: update['status'] || 'pending',
+                    rawInput: update['rawInput'],
+                };
+                this.emit('toolCall', event);
+                break;
+            }
+            case 'available_commands_update': {
+                if (Array.isArray(update['availableCommands'])) {
+                    this._availableCommands = update['availableCommands'];
+                }
+                break;
+            }
+            default:
+                // Ignore other session update types
+                break;
+        }
+        this.emit('sessionUpdate', params);
+    }
+    ensureConnection() {
+        if (!this.connection || !this.isConnected) {
+            throw new Error('Not connected to ACP agent');
+        }
+        return this.connection;
+    }
+}
+//# sourceMappingURL=AcpBridge.js.map

package/dist/AcpBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcpBridge.js","sourceRoot":"","sources":["../src/AcpBridge.ts"],"names":[],"mappings":"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"}

package/dist/BlockStreamer.d.ts

@@ -0,0 +1,54 @@
+/**
+ * BlockStreamer — progressive multi-message delivery for channels.
+ *
+ * Accumulates text chunks from the agent's streaming response and emits
+ * completed "blocks" (paragraphs / sections) as separate channel messages
+ * while the agent is still working. This gives users a natural conversation
+ * flow instead of waiting 30–120 seconds for a single wall of text.
+ *
+ * Emission triggers:
+ *  1. Buffer ≥ maxChars → force-split at best break point
+ *  2. Buffer ≥ minChars AND a paragraph boundary (\n\n) exists → emit up to boundary
+ *  3. Idle timer fires (no chunk for idleMs) AND buffer ≥ minChars → emit buffer
+ *  4. flush() called (response complete) → emit everything remaining
+ *
+ * All sends are serialized — the next block waits for the previous send to complete.
+ */
+export interface BlockStreamerOptions {
+    /** Minimum characters before emitting a block. Default: 400. */
+    minChars: number;
+    /** Force-emit when buffer exceeds this size. Default: 1000. */
+    maxChars: number;
+    /** Emit buffered text after this many ms of inactivity. Default: 1500. */
+    idleMs: number;
+    /** Callback to deliver a completed block. Called with trimmed text. */
+    send: (text: string) => Promise<void>;
+}
+export declare class BlockStreamer {
+    private buffer;
+    private idleTimer;
+    private sending;
+    private opts;
+    /** Number of blocks emitted so far. */
+    blockCount: number;
+    constructor(opts: BlockStreamerOptions);
+    /** Feed a new text chunk from the agent stream. */
+    push(chunk: string): void;
+    /** Flush all remaining buffered text. Awaits all pending sends. */
+    flush(): Promise<void>;
+    private checkEmit;
+    private onIdle;
+    private emitBlock;
+    /**
+     * Find the last paragraph boundary (\n\n) in the buffer.
+     * Returns the position after the boundary, or -1 if no suitable boundary
+     * exists at or after minChars.
+     */
+    private findBlockBoundary;
+    /**
+     * Find the best break point at or before maxPos.
+     * Prefers paragraph break > newline > space > maxPos.
+     */
+    private findBreakPoint;
+    private clearIdleTimer;
+}