@evgenyy/lessinbox-channel 0.1.8 → 0.1.10

package/README.md

@@ -4,11 +4,13 @@ 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
+- Exposes guardrails middleware helpers for side-effect tooling (`executeLessinboxGuardedExecution`)
 
 ## Package contents
 
@@ -22,6 +24,7 @@ Openclaw channel plugin that sends and receives agent conversation state through
 {
   "channels": {
     "lessinbox": {
+      "enabled": true,
       "accounts": {
         "default": {
           "enabled": true,
@@ -34,7 +37,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
           }
         }
@@ -56,14 +59,14 @@ If `threadId` and `runId` are missing, the plugin will create a new Lessinbox ru
 
 Target formats supported by the plugin:
 
-- `channel:<channelId>` - create/continue conversation for that channel
+- `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:
 
@@ -79,7 +82,52 @@ 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.
+
+## Guardrails middleware usage
+
+Use this helper when Openclaw is about to execute a side-effecting tool action (email, payments, external writes).
+
+```ts
+import { executeLessinboxGuardedExecution } from "@evgenyy/lessinbox-channel"
+
+await executeLessinboxGuardedExecution({
+  config: runtimeConfig,
+  accountId: "default",
+  scope: {
+    work_item_id: "wi_123",
+    run_id: "run_123",
+    thread_id: "thr_123"
+  },
+  tool: "email",
+  action: "send",
+  request: {
+    to: "user@example.com",
+    subject: "Status update"
+  },
+  side_effects: {
+    provider: "smtp"
+  },
+  onApprovalRequired: async ({ approval_request_id }) => {
+    // Optional: wait until someone approves this request in Lessinbox.
+    console.log("Approval required:", approval_request_id)
+  },
+  execute: async () => {
+    // your real side effect call
+    return { ok: true }
+  }
+})
+```
+
+This enforces Lessinbox policy decisions (`deny`, `require_simulation`, `require_approval`) and writes execution records before/after side effects.
 
 ## 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;
@@ -39,11 +40,223 @@ export interface InterruptCreateInput {
     deadline_at?: string;
     impact?: string;
 }
+export type GuardrailsDecision = "allow" | "deny" | "require_approval" | "require_simulation";
+export interface GuardrailsEvaluateInput {
+    tool: string;
+    action: string;
+    request?: unknown;
+    side_effects?: unknown;
+    metadata?: unknown;
+    action_hash?: string;
+}
+export interface GuardrailsEvaluateResponse {
+    decision: GuardrailsDecision;
+    reason: string;
+    policy_id: string;
+    policy_version: string;
+    requires_approval: boolean;
+    requires_simulation: boolean;
+    action_hash: string;
+    context_hash: string;
+    matched_rules: Array<{
+        policy_id: string;
+        policy_name?: string;
+        policy_version: string;
+        rule_name?: string;
+        decision: GuardrailsDecision;
+        reason?: string;
+    }>;
+    policy_decision_id?: string;
+    evaluated_at: string;
+}
+export interface SimulationCreateInput {
+    work_item_id?: string | null;
+    run_id?: string | null;
+    thread_id?: string | null;
+    mode?: "dry_run" | "read_only_probe" | "sandbox";
+    tool: string;
+    action: string;
+    request?: unknown;
+    side_effects?: unknown;
+    metadata?: unknown;
+    action_hash?: string;
+}
+export interface SimulationCreateResponse {
+    simulation_id: string;
+    work_item_id?: string;
+    run_id?: string;
+    thread_id?: string;
+    mode: string;
+    status: "completed";
+    action_hash: string;
+    input_hash: string;
+    simulation_hash: string;
+    guardrails_decision: GuardrailsDecision;
+    guardrails_reason: string;
+    plan: unknown;
+    predicted_risks: unknown;
+    predicted_costs: unknown;
+    created_at: string;
+    completed_at: string;
+}
+export type ApprovalStatus = "pending" | "approved" | "denied" | "canceled";
+export interface ApprovalCreateInput {
+    work_item_id?: string | null;
+    run_id?: string | null;
+    thread_id?: string | null;
+    tool: string;
+    action: string;
+    request?: unknown;
+    side_effects?: unknown;
+    simulation_id?: string | null;
+    simulation_hash?: string | null;
+    reason?: string;
+    expires_at?: string;
+    metadata?: unknown;
+    action_hash?: string;
+}
+export interface ApprovalCreateResponse {
+    approval_request_id: string;
+    status: ApprovalStatus;
+    action_hash: string;
+    work_item_id?: string;
+    run_id?: string;
+    thread_id?: string;
+    simulation_id?: string;
+    simulation_hash?: string;
+    created_at: string;
+    expires_at?: string;
+}
+export interface ApprovalDecideInput {
+    decision: "approved" | "denied" | "canceled";
+    comment?: string;
+    metadata?: unknown;
+}
+export interface ApprovalDecideResponse {
+    approval_request_id: string;
+    status: ApprovalStatus;
+    action_hash: string;
+    decision_comment?: string;
+    decided_at: string;
+}
+export type ExecutionStatus = "planned" | "running" | "succeeded" | "failed" | "canceled" | "blocked" | "skipped";
+export interface ExecutionCreateInput {
+    work_item_id?: string | null;
+    run_id?: string | null;
+    thread_id?: string | null;
+    actor_type?: "user" | "agent" | "system";
+    tool: string;
+    action: string;
+    request?: unknown;
+    response?: unknown;
+    side_effects?: unknown;
+    logs?: unknown;
+    status?: ExecutionStatus;
+    error?: unknown;
+    idempotency_key?: string | null;
+    started_at?: string;
+    ended_at?: string;
+    metadata?: unknown;
+}
+export interface ExecutionCreateResponse {
+    execution_id: string;
+    work_item_id?: string;
+    run_id?: string;
+    thread_id?: string;
+    status: ExecutionStatus;
+    created_at: string;
+}
+export interface LessinboxGuardedExecutionScope {
+    work_item_id?: string | null;
+    run_id?: string | null;
+    thread_id?: string | null;
+}
+export interface LessinboxGuardedExecutionInput<T> {
+    config: unknown;
+    accountId?: string;
+    scope?: LessinboxGuardedExecutionScope;
+    tool: string;
+    action: string;
+    request?: unknown;
+    side_effects?: unknown;
+    metadata?: Record<string, unknown>;
+    approval_reason?: string;
+    simulation_mode?: "dry_run" | "read_only_probe" | "sandbox";
+    onApprovalRequired?: (input: {
+        approval_request_id: string;
+        action_hash: string;
+    }) => void | Promise<void>;
+    execute: () => Promise<T>;
+}
+export interface LessinboxGuardedExecutionResult<T> {
+    action_hash: string;
+    guardrails: GuardrailsEvaluateResponse;
+    simulation?: SimulationCreateResponse;
+    approval?: ApprovalCreateResponse;
+    preflight_execution: ExecutionCreateResponse;
+    final_execution: ExecutionCreateResponse;
+    result: T;
+}
 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;
@@ -66,6 +279,12 @@ export interface SubscribeToLessinboxEventsInput {
     accountId?: string;
     onEvent: LessinboxInboundEventHandler;
 }
+export declare function hashActionPayload(input: {
+    tool: string;
+    action: string;
+    request?: unknown;
+    side_effects?: unknown;
+}): string;
 export declare function shutdownLessinboxPluginResources(): Promise<void>;
 export declare class LessinboxApi {
     private readonly apiUrl;
@@ -97,33 +316,76 @@ export declare class LessinboxApi {
         session_id?: string;
         status: string;
     }>;
+    evaluateGuardrails(input: GuardrailsEvaluateInput): Promise<GuardrailsEvaluateResponse>;
+    createSimulation(input: SimulationCreateInput): Promise<SimulationCreateResponse>;
+    createApproval(input: ApprovalCreateInput): Promise<ApprovalCreateResponse>;
+    decideApproval(approvalRequestId: string, input: ApprovalDecideInput): Promise<ApprovalDecideResponse>;
+    createExecution(input: ExecutionCreateInput): Promise<ExecutionCreateResponse>;
     completeRun(runId: string, summary?: string): Promise<void>;
     failRun(runId: string, error: {
         kind: string;
         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 = {
+export declare function createLessinboxApiFromConfig(input: {
+    config: unknown;
+    accountId?: string;
+}): {
+    accountId: string;
+    account: LessinboxAccountConfig;
+    api: LessinboxApi;
+};
+export declare function executeLessinboxGuardedExecution<T>(input: LessinboxGuardedExecutionInput<T>): Promise<LessinboxGuardedExecutionResult<T>>;
+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;
@@ -139,18 +401,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: {
@@ -163,18 +430,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 {};