@evgenyy/lessinbox-channel 0.1.6 → 0.1.9

package/README.md

@@ -4,9 +4,10 @@ Openclaw channel plugin that sends and receives agent conversation state through
 
 ## What it does
 
-- Starts Lessinbox sessions (runs) when needed
+- Keeps one continuous conversation per target (`channel:*` or `thread:*`)
+- Starts new Lessinbox sessions (runs) only when needed
 - Posts assistant messages into Lessinbox threads
-- Maintains persistent `conversationId -> { threadId, runId }` mapping (`memory` or `redis`)
+- Maintains persistent `conversationId -> { threadId, runId? }` mapping (`memory` or `redis`)
 - Opens workspace WebSocket stream and emits realtime inbound events (`message.created`, `interrupt.answered`, `run.state_changed`, etc.)
 - Exposes a channel plugin manifest + Lessinbox skill bundle
 
@@ -22,6 +23,7 @@ Openclaw channel plugin that sends and receives agent conversation state through
 {
   "channels": {
     "lessinbox": {
+      "enabled": true,
       "accounts": {
         "default": {
           "enabled": true,
@@ -34,7 +36,7 @@ Openclaw channel plugin that sends and receives agent conversation state through
           "redisPrefix": "lessinbox:openclaw",
           "workspaceStream": {
             "enabled": true,
-            "wsUrl": "wss://lessinbox.example.com/v1/ws",
+            "wsUrl": "wss://lessinbox.example.com/v2/ws",
             "reconnectMs": 1500
           }
         }
@@ -50,13 +52,20 @@ The plugin expects Openclaw to call `outbound.sendText(...)` with:
 
 - `text` (required)
 - `config` (runtime config object)
-- optional: `accountId`, `channelId`, `title`, `threadId`, `runId`, `conversationId`, `metadata`
+- optional: `accountId`, `target`, `channelId`, `title`, `threadId`, `runId`, `conversationId`, `metadata`
 
 If `threadId` and `runId` are missing, the plugin will create a new Lessinbox run and use that thread.
 
+Target formats supported by the plugin:
+
+- `channel:<channelId>` - continue the latest thread for this channel (or create one if missing)
+- `thread:<threadId>` - create/continue conversation in that exact thread
+- raw channel id (`cml...` or `chn_...`) - treated as `channel:<id>`
+- account alias (`default`, etc.) - switches account when it matches configured account id
+
 ## Realtime inbound usage
 
-The package exports `subscribeToLessinboxEvents(...)` and also exposes `plugin.inbound.subscribe(...)`.
+The package exports `subscribeToLessinboxEvents(...)` as a direct helper for custom integrations.
 
 Example:
 
@@ -72,7 +81,15 @@ const unsubscribe = subscribeToLessinboxEvents({
 })
 ```
 
-On terminal run states (`completed`, `failed`, `canceled`) the plugin clears stored run mapping automatically.
+For Openclaw-native runtime lifecycle, inbound processing is wired through channel gateway hooks:
+
+- `plugin.gateway.startAccount(...)` subscribes to Lessinbox workspace stream.
+- `plugin.gateway.stopAccount(...)` unsubscribes and shuts down account listeners.
+- Incoming `message.created` user messages are routed through Openclaw runtime reply dispatcher.
+
+This is the preferred runtime path in v2.
+
+On terminal run states (`completed`, `failed`, `canceled`) the plugin keeps thread mapping and clears only the run id, so the next outbound message starts a fresh run in the same thread.
 
 ## Build
 

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export interface LessinboxWorkspaceStreamConfig {
     reconnectMs?: number;
 }
 export interface LessinboxAccountConfig {
+    accountId?: string;
     enabled?: boolean;
     apiUrl: string;
     apiKey: string;
@@ -41,9 +42,64 @@ export interface InterruptCreateInput {
 }
 export interface LessinboxRunRef {
     threadId: string;
-    runId: string;
+    runId?: string;
     status?: string;
 }
+interface V2RunSnapshot {
+    id: string;
+    thread_id: string | null;
+    channel_id: string;
+    status: string;
+}
+interface V2RunGetResponse {
+    run: V2RunSnapshot;
+}
+interface V2ThreadRunSnapshot {
+    id: string;
+    status: string;
+}
+interface V2ThreadGetResponse {
+    id: string;
+    channel_id: string;
+    run: V2ThreadRunSnapshot | null;
+    session?: V2ThreadRunSnapshot | null;
+}
+interface V2ThreadSummary {
+    id: string;
+    channel_id: string;
+    run_id: string | null;
+    run_status: string | null;
+    session_id?: string | null;
+    session_status?: string | null;
+}
+interface V2ThreadListResponse {
+    threads: V2ThreadSummary[];
+    next_cursor: string | null;
+}
+interface V2MessageActor {
+    type?: string;
+    user_id?: string;
+    userId?: string;
+    agent_id?: string;
+    agentId?: string;
+}
+interface V2ThreadFeedMessage {
+    id: string;
+    run_id?: string | null;
+    session_id?: string | null;
+    kind?: string | null;
+    text?: string | null;
+    actor?: V2MessageActor;
+    created_at?: string;
+}
+interface V2ThreadFeedEntry {
+    type?: string;
+    message?: V2ThreadFeedMessage;
+}
+interface V2ThreadFeedResponse {
+    entries: V2ThreadFeedEntry[];
+    next_cursor: string | null;
+}
 export type LessinboxWorkspaceEventKind = "event.appended" | "artifact.ready" | "checkpoint.created" | "checkpoint.resolved" | "run.status" | "thread.summary" | "message.created" | "interrupt.opened" | "interrupt.answered" | "run.state_changed";
 export interface LessinboxWorkspaceEvent {
     kind: string;
@@ -103,32 +159,64 @@ export declare class LessinboxApi {
         message: string;
         details?: Record<string, unknown>;
     }): Promise<void>;
+    getRun(runId: string): Promise<V2RunGetResponse>;
+    getThread(threadId: string): Promise<V2ThreadGetResponse>;
     listThreads(input?: {
         bucket?: "needs_input" | "in_progress" | "done" | "all";
         channelId?: string;
         cursor?: string;
         limit?: number;
-    }): Promise<{
-        threads: unknown[];
-        next_cursor: string | null;
-    }>;
+    }): Promise<V2ThreadListResponse>;
     createWorkspaceWsToken(): Promise<{
         token: string;
         expires_at: string;
     }>;
+    getThreadFeed(input: {
+        threadId: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<V2ThreadFeedResponse>;
     private request;
 }
 export declare function resolveAccountConfig(config: unknown, accountId?: string): LessinboxAccountConfig;
-type ChannelPluginRuntimeAPI = {
+type ChannelLogSink = {
+    debug?: (message: string) => void;
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+    error?: (message: string) => void;
+};
+type ChannelRuntimeState = Record<string, unknown>;
+type ChannelGatewayContext = {
+    cfg: unknown;
+    accountId: string;
+    account: LessinboxAccountConfig;
+    runtime: unknown;
+    abortSignal: AbortSignal;
+    log?: ChannelLogSink;
+    getStatus: () => ChannelRuntimeState;
+    setStatus: (next: ChannelRuntimeState) => void;
+};
+type ChannelGatewayStartContext = ChannelGatewayContext;
+type ChannelGatewayStopContext = ChannelGatewayContext;
+type OpenclawPluginService = {
+    id: string;
+    start: (ctx: unknown) => void | Promise<void>;
+    stop?: (ctx: unknown) => void | Promise<void>;
+};
+type OpenclawPluginApi = {
+    runtime?: unknown;
     registerChannel: (input: {
         plugin: unknown;
-    }) => void;
-    onShutdown?: (handler: () => Promise<void> | void) => void;
+    } | unknown) => void;
+    registerService?: (service: OpenclawPluginService) => void;
 };
 type SendTextInput = {
     text: string;
     accountId?: string;
     config?: unknown;
+    target?: string;
+    to?: string;
+    recipient?: string;
     channelId?: string;
     title?: string;
     threadId?: string;
@@ -136,18 +224,23 @@ type SendTextInput = {
     conversationId?: string;
     metadata?: Record<string, unknown>;
 };
-type SubscribeInput = {
-    config?: unknown;
-    accountId?: string;
-    onEvent: LessinboxInboundEventHandler;
+type SendMediaInput = Omit<SendTextInput, "text"> & {
+    text?: string;
+    mediaUrl?: string;
 };
 declare function sendTextToLessinbox(input: SendTextInput): Promise<{
     ok: boolean;
     threadId: string;
     runId: string;
 }>;
+declare function sendMediaToLessinbox(input: SendMediaInput): Promise<{
+    ok: boolean;
+    threadId: string;
+    runId: string;
+}>;
+declare function startLessinboxGatewayAccount(ctx: ChannelGatewayStartContext): Promise<void>;
+declare function stopLessinboxGatewayAccount(ctx: ChannelGatewayStopContext): Promise<void>;
 export declare function subscribeToLessinboxEvents(input: SubscribeToLessinboxEventsInput): () => void;
-declare function subscribeFromPlugin(input: SubscribeInput): () => void;
 export declare function createLessinboxPlugin(): {
     id: string;
     meta: {
@@ -160,18 +253,45 @@ export declare function createLessinboxPlugin(): {
     };
     capabilities: {
         chatTypes: string[];
+        threads: boolean;
+        media: boolean;
+    };
+    reload: {
+        configPrefixes: string[];
     };
     config: {
         listAccountIds: (cfg: unknown) => string[];
         resolveAccount: (cfg: unknown, accountId?: string) => LessinboxAccountConfig;
+        isConfigured: (account: LessinboxAccountConfig) => boolean;
+        describeAccount: (account: LessinboxAccountConfig) => {
+            accountId: string;
+            enabled: boolean;
+            configured: boolean;
+            workspaceId: string;
+            apiUrl: string;
+        };
     };
     outbound: {
         deliveryMode: string;
         sendText: typeof sendTextToLessinbox;
+        sendMedia: typeof sendMediaToLessinbox;
+    };
+    gateway: {
+        startAccount: typeof startLessinboxGatewayAccount;
+        stopAccount: typeof stopLessinboxGatewayAccount;
     };
-    inbound: {
-        subscribe: typeof subscribeFromPlugin;
+    status: {
+        defaultRuntime: {
+            accountId: string;
+            running: boolean;
+            connected: boolean;
+            lastConnectedAt: null;
+            lastDisconnect: null;
+            lastStartAt: null;
+            lastStopAt: null;
+            lastError: null;
+        };
     };
 };
-export default function register(api: ChannelPluginRuntimeAPI): void;
+export default function register(api: OpenclawPluginApi): void;
 export {};