@marswave/cola-plugin-sdk

Cola Plugin SDK

TypeScript SDK for building Cola channel plugins.

Channel plugins connect external message platforms to Cola. A plugin receives messages from a platform, delivers normalized prompts into Cola, and sends Cola's reply back through the same platform without importing Cola server internals.

English | 中文

Package

pnpm add @marswave/cola-plugin-sdk

When testing against an unreleased Cola checkout, link to the local SDK package from the same checkout as the server:

{
  "dependencies": {
    "@marswave/cola-plugin-sdk": "link:/path/to/cola/packages/plugin-sdk"
  }
}

Public API

• defineChannel() for the standard channel-plugin shape.
• definePlugin() for plugins that combine a channel with commands or future capability slots.
• Public types for plugin metadata, channel capabilities, gateway adapters, outbound delivery, auth, config schemas, commands, host runtime APIs, STT/TTS, and session lifecycle events.
• createPollLoop() and withBackoff() helper utilities for polling channels.

The SDK is the compatibility boundary for distributed plugins. Do not import files from Cola's desktop app, server, or shared internal modules in a plugin that will be installed by users.

Minimal Channel Plugin

import { defineChannel } from '@marswave/cola-plugin-sdk'
import type { GatewayContext, OutboundContext } from '@marswave/cola-plugin-sdk'

type GatewayState = {
  startedAt?: number
}

export default defineChannel<GatewayState>({
  id: 'example',
  meta: {
    label: 'Example',
    description: 'Example message channel',
    markdownCapable: true
  },
  capabilities: {
    receive: { text: true },
    send: { text: true, markdown: true }
  },
  gateway: {
    async start(ctx: GatewayContext<GatewayState>) {
      ctx.state.startedAt = Date.now()

      await ctx.deliver({
        sessionId: ['dm', 'owner'],
        sender: { id: 'owner', name: 'Owner' },
        deliveryContext: { to: 'owner' },
        message: 'Hello from the example plugin'
      })
    },
    async stop(ctx) {
      ctx.logger.info('Example channel stopped')
    },
    getStatus() {
      return { connected: true, configured: true }
    }
  },
  outbound: {
    async sendText(ctx: OutboundContext) {
      // Send ctx.text back to the platform represented by ctx.deliveryContext.
    }
  }
})

Plugin Metadata

Cola discovers installed plugins from ~/.cola/plugins/<id>/package.json. The package must include a cola.plugin manifest. Channel plugins should also add cola.channel display metadata.

{
  "name": "cola-plugin-example",
  "version": "0.1.0",
  "type": "module",
  "dependencies": {
    "@marswave/cola-plugin-sdk": "^0.5.0"
  },
  "cola": {
    "plugin": {
      "id": "example",
      "entry": "./dist/index.js",
      "minSdkVersion": "0.5.0"
    },
    "channel": {
      "label": "Example",
      "description": "Example message channel",
      "aliases": ["ex"],
      "docsPath": "/channels/example"
    }
  }
}

Build or bundle the plugin entry before installing it. cola.plugin.entry must point to JavaScript that Cola can import at runtime.

Core Concepts

Gateway

The gateway adapter owns the platform receive loop. It can run long polling, connect to a WebSocket, subscribe to a queue, or use any platform-specific mechanism. For each accepted inbound message, call ctx.deliver() with a stable sessionId, the sender, optional routing data, normalized text, and optional attachments.

Cola owns the plugin:<pluginId>: scope prefix. Plugins only choose the session suffix, such as ['dm', userId] or ['room', roomId].

Outbound

The outbound adapter sends Cola's reply back to the platform represented by deliveryContext. sendText() is required when the channel can send text. Optional methods handle media, typing indicators, and reactions.

Auth And Identity

The auth adapter runs login and disconnect flows. QR-code and status updates can be surfaced with ctx.onQrCode() and ctx.onStatus(). After a platform account is authorized, call ctx.runtime.identity.bind(senderId) so Cola accepts messages from that sender. Disconnect flows should call unbind().

Host Runtime

ctx.runtime exposes host services that are safe for plugins:

• identity for channel user binding.
• config.get() for readonly plugin config.
• events.on() for plugin-scoped session events.
• stt and tts for host-provided local speech services when available.
• logger for local logging and explicit error reporting.
• reloadGateway() for restarting receive loops after config or auth changes.

Local Testing

Use the Cola CLI that belongs to the same checkout as the server you are testing:

pnpm cli:dev plugin install /path/to/plugin
pnpm cli:dev channel login example
pnpm cli:dev channel status

The development server should also come from the same checkout, otherwise it may not understand the current SDK shape or plugin manifest metadata.

Compatibility

The SDK follows semver after publication. Removing or changing a public export is a breaking change. Types and adapters marked @internal may change before they become stable.

License

MIT. See LICENSE.

MIT is intentionally permissive: plugin authors can use the SDK in open-source, commercial, or private plugins as long as they preserve the copyright notice and license text.