@parall/parall 1.30.0 → 1.32.0

package/src/gateway.ts

@@ -1,21 +1,30 @@
-import type { PluginRuntime } from "openclaw/plugin-sdk";
-import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+import type { PluginRuntime } from 'openclaw/plugin-sdk';
+import type { ChannelPlugin } from 'openclaw/plugin-sdk/core';
 
 /** Extract ChannelGatewayAdapter from ChannelPlugin (removed from public SDK exports in 2026.3.24). */
-type ChannelGatewayAdapter<T = unknown> = NonNullable<ChannelPlugin<T>["gateway"]>;
+type ChannelGatewayAdapter<T = unknown> = NonNullable<ChannelPlugin<T>['gateway']>;
 import {
   ParallAgentGateway,
   parseShutdownDeadlineMs,
+  parseForkDeadlineMs,
+  parseDispatchDeadlineMs,
+  initAgentTelemetry,
+  createOtelLogger,
   type DispatchAdapter,
   type ParallEvent,
   type RuntimeEvent,
-} from "@parall/agent-core";
-import { ApiError, ParallClient, ParallWs } from "@parall/sdk";
-import type { ParallChannelConfig } from "./types.js";
-import * as crypto from "node:crypto";
-import * as os from "node:os";
-import * as path from "node:path";
-import { resolveParallAccount } from "./accounts.js";
+} from '@parall/agent-core';
+import {
+  appendPreparedLocalAttachmentRefs,
+  ensureLocalAttachmentGitExclude,
+  pinLocalAttachmentPaths,
+} from '@parall/agent-core/internal/attachment-input';
+import { ApiError, ParallClient, ParallWs } from '@parall/sdk';
+import type { ParallChannelConfig } from './types.js';
+import * as crypto from 'node:crypto';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { resolveParallAccount } from './accounts.js';
 import {
   getParallRuntime,
   removeParallAccountState,
@@ -23,18 +32,24 @@ import {
   setAgentSessionBinding,
   setDispatchGroupKey,
   setParallAccountState,
-} from "./runtime.js";
-import { buildOrchestratorSessionKey } from "./session.js";
-import type { ResolvedParallAccount } from "./types.js";
-import { fetchAndApplyPlatformConfig } from "./config-manager.js";
-import { startWikiHelper } from "./wiki-helper.js";
-import { SessionManager } from "./oc-session.js";
-import { cleanupForkSession, clearSessionState, forkOrchestratorSession, resolveSessionId, resolveTranscriptFile } from "./fork.js";
+} from './runtime.js';
+import { buildOrchestratorSessionKey } from './session.js';
+import type { ResolvedParallAccount } from './types.js';
+import { fetchAndApplyPlatformConfig } from './config-manager.js';
+import { startWikiHelper } from './wiki-helper.js';
+import { SessionManager } from './oc-session.js';
+import {
+  cleanupForkSession,
+  clearSessionState,
+  forkOrchestratorSession,
+  resolveSessionId,
+  resolveTranscriptFile,
+} from './fork.js';
 
 function resolveWsUrl(account: ResolvedParallAccount): string {
   if (account.config.ws_url) return account.config.ws_url;
-  const base = account.config.parall_url.replace(/\/$/, "");
-  const wsBase = base.replace(/^http/, "ws");
+  const base = account.config.parall_url.replace(/\/$/, '');
+  const wsBase = base.replace(/^http/, 'ws');
   return `${wsBase}/ws`;
 }
 
@@ -70,15 +85,15 @@ function buildInboundCtx(
     To: `parall:orchestrator`,
     SessionKey: sessionKey,
     AccountId: accountId,
-    ChatType: event.targetType ?? "unknown",
+    ChatType: event.targetType ?? 'unknown',
     SenderName: event.senderName,
     SenderId: event.senderId,
-    Provider: "parall" as const,
-    Surface: "parall" as const,
+    Provider: 'parall' as const,
+    Surface: 'parall' as const,
     MessageSid: event.messageId,
     Timestamp: Date.now(),
     CommandAuthorized: true,
-    OriginatingChannel: "parall" as const,
+    OriginatingChannel: 'parall' as const,
     OriginatingTo: `parall:orchestrator`,
   });
 }
@@ -91,13 +106,13 @@ function buildInboundHistory(events: ParallEvent[]): Array<{ sender: string; bod
     if (event.threadRootId) meta.push(`[Thread: ${event.threadRootId}]`);
     if (event.attachments?.length) {
       for (const att of event.attachments) {
-        const safeMime = att.mimeType.replace(/[\r\n[\]|]/g, " ").trim();
+        const safeMime = att.mimeType.replace(/[\r\n[\]|]/g, ' ').trim();
         meta.push(`[Attachment: prll://${att.id} | ${safeMime}]`);
       }
     }
     return {
       sender: event.senderName,
-      body: meta.length > 0 ? `${meta.join(" ")}\n${event.body}` : event.body,
+      body: meta.length > 0 ? `${meta.join(' ')}\n${event.body}` : event.body,
     };
   });
 }
@@ -185,68 +200,106 @@ function createOpenClawDispatchAdapter(opts: {
   cfg: Record<string, unknown>;
   accountId: string;
   sessionsDir: string;
+  workspaceDir: string;
 }): DispatchAdapter {
+  const activeStreams = new Map<string, ReturnType<typeof createRuntimeEventStream>>();
+
   return {
-    async *dispatch({ event, earlierEvents = [], bodyForAgent, sessionKey }) {
-      const stream = createRuntimeEventStream();
-      let reasoningBuffer = "";
-      let turnGroupKey = "";
+    abortDispatch(sessionKey: string): void {
+      activeStreams.get(sessionKey)?.fail(new Error('dispatch deadline exceeded'));
+    },
 
-      const run = opts.core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-        ctx: buildInboundCtx(opts.core, opts.accountId, event, sessionKey, bodyForAgent, earlierEvents),
-        cfg: opts.cfg,
-        dispatcherOptions: {
-          deliver: async (payload: { text?: string }) => {
-            const replyText = payload.text?.trim();
-            if (!replyText) return;
-            stream.push({
-              type: "text",
-              text: replyText,
-              project: false,
-              groupKey: turnGroupKey || undefined,
-            });
-          },
-          onReplyStart: () => {
-            turnGroupKey = crypto.randomUUID();
-            setDispatchGroupKey(sessionKey, turnGroupKey);
-          },
-        },
-        replyOptions: {
-          onReasoningStream: (payload: { text?: string }) => {
-            reasoningBuffer += payload.text ?? "";
+    async *dispatch({ event, earlierEvents = [], bodyForAgent, sessionKey, context }) {
+      let promptBody = bodyForAgent;
+      let releasePreparedAttachments = () => {};
+      try {
+        const prepared = await appendPreparedLocalAttachmentRefs(bodyForAgent, event, context, {
+          workspaceDir: opts.workspaceDir,
+          log: context.log,
+        });
+        promptBody = prepared.body;
+        releasePreparedAttachments = pinLocalAttachmentPaths(prepared.attachments.images);
+      } catch (err) {
+        context.log?.warn?.(`failed to prepare local attachments: ${String(err)}`);
+      }
+
+      try {
+        const stream = createRuntimeEventStream();
+        activeStreams.set(sessionKey, stream);
+        let reasoningBuffer = '';
+        let turnGroupKey = '';
+
+        const run = opts.core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+          ctx: buildInboundCtx(
+            opts.core,
+            opts.accountId,
+            event,
+            sessionKey,
+            promptBody,
+            earlierEvents,
+          ),
+          cfg: opts.cfg,
+          dispatcherOptions: {
+            deliver: async (payload: { text?: string }) => {
+              const replyText = payload.text?.trim();
+              if (!replyText) return;
+              stream.push({
+                type: 'text',
+                text: replyText,
+                project: false,
+                groupKey: turnGroupKey || undefined,
+              });
+            },
+            onReplyStart: () => {
+              turnGroupKey = crypto.randomUUID();
+              setDispatchGroupKey(sessionKey, turnGroupKey);
+            },
           },
-          onReasoningEnd: async () => {
-            if (!reasoningBuffer) return;
-            stream.push({
-              type: "thinking",
-              text: reasoningBuffer,
-              groupKey: turnGroupKey || undefined,
-            });
-            reasoningBuffer = "";
+          replyOptions: {
+            onReasoningStream: (payload: { text?: string }) => {
+              reasoningBuffer += payload.text ?? '';
+            },
+            onReasoningEnd: async () => {
+              if (!reasoningBuffer) return;
+              stream.push({
+                type: 'thinking',
+                text: reasoningBuffer,
+                groupKey: turnGroupKey || undefined,
+              });
+              reasoningBuffer = '';
+            },
           },
-        },
-      });
+        });
 
-      run.then(() => stream.end()).catch((err) => stream.fail(err));
-      let sessionId: string | null;
-      try {
-        sessionId = await Promise.race([
-          waitForOpenClawSessionId(opts.sessionsDir, sessionKey),
-          run.then(() => null as string | null, (err) => { throw err; }),
-        ]);
-      } catch {
-        sessionId = null;
-      }
-      if (!sessionId) {
-        stream.fail(new Error(`OpenClaw did not expose a sessionId for ${sessionKey}`));
-      } else {
-        yield {
-          type: "runtime_session",
-          runtimeSessionId: sessionId,
-          runtimeLaneKey: sessionKey,
-        };
+        run.then(() => stream.end()).catch((err) => stream.fail(err));
+        let sessionId: string | null;
+        try {
+          sessionId = await Promise.race([
+            waitForOpenClawSessionId(opts.sessionsDir, sessionKey),
+            run.then(
+              () => null as string | null,
+              (err) => {
+                throw err;
+              },
+            ),
+          ]);
+        } catch {
+          sessionId = null;
+        }
+        if (!sessionId) {
+          stream.fail(new Error(`OpenClaw did not expose a sessionId for ${sessionKey}`));
+        } else {
+          yield {
+            type: 'runtime_session',
+            runtimeSessionId: sessionId,
+            runtimeLaneKey: sessionKey,
+          };
+        }
+        yield* stream.stream();
+      } finally {
+        activeStreams.delete(sessionKey);
+        releasePreparedAttachments();
       }
-      yield* stream.stream();
     },
 
     getBranchPoint(sessionKey: string): string | undefined {
@@ -273,7 +326,7 @@ function createOpenClawDispatchAdapter(opts: {
     },
 
     cleanupFork({ fork }) {
-      if (typeof fork.sessionFile !== "string") return;
+      if (typeof fork.sessionFile !== 'string') return;
       cleanupForkSession({
         sessionFile: fork.sessionFile,
         sessionKey: fork.sessionKey,
@@ -287,7 +340,8 @@ export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
   startAccount: async (ctx) => {
     const account = resolveParallAccount({ cfg: ctx.cfg, accountId: ctx.accountId });
     if (!account.enabled) return;
-    if (!account.configured) throw new Error("Parall account is not configured: parall_url/api_key/org_id required");
+    if (!account.configured)
+      throw new Error('Parall account is not configured: parall_url/api_key/org_id required');
 
     const { config } = account;
     const core = getParallRuntime();
@@ -308,109 +362,125 @@ export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
     });
     log?.info(`parall[${ctx.accountId}]: authenticated as ${me.display_name} (${agentUserId})`);
 
-    const stateDir = process.env.OPENCLAW_STATE_DIR
-      || path.join(process.env.HOME || "/data", ".openclaw");
-    const openclawConfigPath = path.join(stateDir, "openclaw.json");
-
-    const configManagerOpts = {
-      client,
-      stateDir,
-      configPath: openclawConfigPath,
-      credentials: { api_key: config.api_key, parall_url: config.parall_url },
-      log,
-    };
-
+    const telemetry = await initAgentTelemetry('parall-openclaw-agent', 'openclaw');
+    const otelLog = createOtelLogger('agent', 'openclaw-agent');
     try {
-      await fetchAndApplyPlatformConfig(configManagerOpts);
-    } catch (err) {
-      log?.warn(`parall[${ctx.accountId}]: platform config fetch failed: ${String(err)}`);
-    }
+      const stateDir =
+        process.env.OPENCLAW_STATE_DIR || path.join(process.env.HOME || '/data', '.openclaw');
+      const openclawConfigPath = path.join(stateDir, 'openclaw.json');
 
-    let stopWikiHelper: (() => void) | null = null;
-    let wikiMountRoot: string | undefined;
-    try {
-      const wikiHelper = await startWikiHelper({
-        accountId: ctx.accountId,
-        parallUrl: config.parall_url,
-        apiKey: config.api_key,
-        orgId: config.org_id,
-        agentId: agentUserId,
+      const configManagerOpts = {
+        client,
         stateDir,
-        log,
-      });
-      wikiMountRoot = wikiHelper.mountRoot;
-      stopWikiHelper = wikiHelper.stop;
-    } catch (err) {
-      log?.warn(`parall[${ctx.accountId}]: wiki helper startup failed: ${String(err)}`);
-    }
+        configPath: openclawConfigPath,
+        credentials: { api_key: config.api_key, parall_url: config.parall_url },
+        log: otelLog,
+      };
 
-    const wsUrl = resolveWsUrl(account);
-    const ws = new ParallWs({
-      getTicket: () => client.getWsTicket(),
-      wsUrl,
-    });
-    const orchestratorKey = buildOrchestratorSessionKey(ctx.accountId);
-    const sessionsDir = path.join(stateDir, "agents", "main", "sessions");
-    const dispatchAdapter = createOpenClawDispatchAdapter({
-      core,
-      cfg: ctx.cfg,
-      accountId: ctx.accountId,
-      sessionsDir,
-    });
-
-    const gateway = new ParallAgentGateway({
-      accountId: ctx.accountId,
-      client,
-      ws,
-      connectionLabel: wsUrl,
-      config: {
-        parall_url: config.parall_url,
-        api_key: config.api_key,
-        org_id: config.org_id,
-      },
-      agentUserId,
-      runtimeType: "openclaw",
-      runtimeKey: orchestratorKey,
-      runtimeRef: { hostname: os.hostname(), pid: process.pid },
-      dispatchAdapter,
-      log,
-      shutdownDeadlineMs: parseShutdownDeadlineMs(process.env.PRLL_SHUTDOWN_DEADLINE_MS),
-      onConfigUpdate: async () => {
+      try {
         await fetchAndApplyPlatformConfig(configManagerOpts);
-      },
-      onSessionReady: async ({ activeSessionId }) => {
-        setParallAccountState(ctx.accountId, {
-          client,
-          apiUrl: config.parall_url,
+      } catch (err) {
+        otelLog.warn(`parall[${ctx.accountId}]: platform config fetch failed: ${String(err)}`);
+      }
+
+      let stopWikiHelper: (() => void) | null = null;
+      let wikiMountRoot: string | undefined;
+      try {
+        const wikiHelper = await startWikiHelper({
+          accountId: ctx.accountId,
+          parallUrl: config.parall_url,
           apiKey: config.api_key,
           orgId: config.org_id,
-          agentUserId,
-          activeSessionId,
-          sessionBindings: new Map<string, string>(),
-          sessionsDir,
-          runtimeRef: { hostname: os.hostname(), pid: process.pid },
-          wikiMountRoot,
-          ws,
-          orchestratorSessionKey: orchestratorKey,
+          agentId: agentUserId,
+          stateDir,
+          log: otelLog,
         });
-      },
-      onSessionBinding: async ({ sessionKey, agentSessionId }) => {
-        setAgentSessionBinding(ctx.accountId, sessionKey, agentSessionId);
-      },
-      onBeforeDisconnect: async () => {
-        stopWikiHelper?.();
-        removeParallAccountState(ctx.accountId);
-      },
-      onNewSession: () => { clearSessionState(sessionsDir, orchestratorKey); },
-    });
+        wikiMountRoot = wikiHelper.mountRoot;
+        stopWikiHelper = wikiHelper.stop;
+      } catch (err) {
+        otelLog.warn(`parall[${ctx.accountId}]: wiki helper startup failed: ${String(err)}`);
+      }
 
-    try {
-      await gateway.run(ctx.abortSignal);
-    } finally {
-      if (!ctx.abortSignal.aborted) {
-        stopWikiHelper?.();
-        removeParallAccountState(ctx.accountId);
+      const wsUrl = resolveWsUrl(account);
+      const ws = new ParallWs({
+        getTicket: () => client.getWsTicket(),
+        wsUrl,
+      });
+      const orchestratorKey = buildOrchestratorSessionKey(ctx.accountId);
+      const sessionsDir = path.join(stateDir, 'agents', 'main', 'sessions');
+      const workspaceDir = process.cwd();
+      ensureLocalAttachmentGitExclude(workspaceDir);
+      const dispatchAdapter = createOpenClawDispatchAdapter({
+        core,
+        cfg: ctx.cfg,
+        accountId: ctx.accountId,
+        sessionsDir,
+        workspaceDir,
+      });
+
+      const gateway = new ParallAgentGateway({
+        accountId: ctx.accountId,
+        client,
+        ws,
+        connectionLabel: wsUrl,
+        config: {
+          parall_url: config.parall_url,
+          api_key: config.api_key,
+          org_id: config.org_id,
+        },
+        agentUserId,
+        runtimeType: 'openclaw',
+        runtimeKey: orchestratorKey,
+        runtimeRef: { hostname: os.hostname(), pid: process.pid },
+        dispatchAdapter,
+        log: otelLog,
+        shutdownDeadlineMs: parseShutdownDeadlineMs(process.env.PRLL_SHUTDOWN_DEADLINE_MS),
+        forkDeadlineMs: parseForkDeadlineMs(process.env.PRLL_FORK_DEADLINE_MS),
+        dispatchDeadlineMs: parseDispatchDeadlineMs(process.env.PRLL_DISPATCH_DEADLINE_MS),
+        onConfigUpdate: async () => {
+          await fetchAndApplyPlatformConfig(configManagerOpts);
+        },
+        onSessionReady: async ({ activeSessionId }) => {
+          setParallAccountState(ctx.accountId, {
+            client,
+            apiUrl: config.parall_url,
+            apiKey: config.api_key,
+            orgId: config.org_id,
+            agentUserId,
+            activeSessionId,
+            sessionBindings: new Map<string, string>(),
+            sessionsDir,
+            runtimeRef: { hostname: os.hostname(), pid: process.pid },
+            wikiMountRoot,
+            ws,
+            orchestratorSessionKey: orchestratorKey,
+          });
+        },
+        onSessionBinding: async ({ sessionKey, agentSessionId }) => {
+          setAgentSessionBinding(ctx.accountId, sessionKey, agentSessionId);
+        },
+        onBeforeDisconnect: async () => {
+          stopWikiHelper?.();
+          removeParallAccountState(ctx.accountId);
+        },
+        onNewSession: () => {
+          clearSessionState(sessionsDir, orchestratorKey);
+        },
+        onSessionStale: () => {
+          clearSessionState(sessionsDir, orchestratorKey);
+        },
+      });
+
+      try {
+        await gateway.run(ctx.abortSignal);
+      } finally {
+        if (!ctx.abortSignal.aborted) {
+          stopWikiHelper?.();
+          removeParallAccountState(ctx.accountId);
+        }
       }
+    } finally {
+      await telemetry.shutdown();
     }
   },
 };