Why this matters

OpenClaw plugins increasingly need to send real files back to the user in the same session lane: support artifacts, generated reports, approval docs, exports, screenshots, and workflow evidence.

Without a generic seam, plugin authors end up with two bad options:

• own Telegram/Slack/Discord delivery logic themselves, including route lookup and transport quirks; or
• push product-specific attachment routes into OpenClaw core.

This PR adds the missing middle layer: a bundled plugin can ask the host to validate local files and deliver them through the active direct-outbound session route, while OpenClaw keeps ownership of channel credentials, delivery routing, formatting quirks, and transport behavior.

What kinds of plugins this could support

This seam is intentionally generic. It can support many plugin families without adding plugin-specific delivery logic to core:

• Support and incident plugins: send logs, screenshots, repro bundles, or diagnostics back into the live support conversation.
• Approval and review plugins: attach generated PDFs, redlines, or diffs into the same operator thread that requested them.
• CRM and case-management plugins: deliver quote files, customer evidence, or case exports to the active session route.
• Field ops and inspection plugins: return photos, signed forms, or inspection reports to the same conversation lane.
• Migration and import plugins: send rejected-record CSVs or validation reports back to a human operator.
• Research and reporting plugins: attach exported summaries or evidence files instead of pasting large blobs into chat.

The important part: the plugin decides what artifact to send. OpenClaw decides whether the file is safe and where the active session route actually goes.

New SDK seam

This PR adds:

• OpenClawPluginApi.sendSessionAttachment(...)
• typed attachment params and result types in the SDK
• host-side file validation, size/count limits, session-route lookup, and stale-registry protection
• workspace-relative resolution against the session agent workspace
• channel hints for caption formatting, Telegram delivery behavior, and Slack thread targeting

Example plugin usage:

const result = await api.sendSessionAttachment({
  sessionKey: "agent:main:main",
  files: [{ path: "./proof-report.txt" }],
  text: "attachment ready",
  captionFormat: "plain",
});

Runtime architecture

flowchart LR
  Plugin["Plugin callback, handler, or workflow"] --> SDK["sendSessionAttachment(...)"]
  SDK --> Validate["Host file validation and workspace resolution"]
  Validate --> Route["Active session route lookup"]
  Route --> Channel["Direct outbound channel adapter"]
  Channel --> User["Delivered attachment in the live session lane"]

The plugin never talks directly to Telegram, Slack, or another channel transport. It asks the host to deliver a validated file to the already-active session route.

Safety and boundaries

This stays intentionally narrow:

• bundled-only: this seam depends on host-managed session and channel integrations
• the host validates file count, size, path, and optional delivery hints before calling the outbound adapter
• relative paths resolve against the session agent workspace instead of whatever host cwd happens to be active
• delivery stays bound to the active session route; plugins do not get arbitrary channel send power
• stale or unloaded plugin registries are rejected instead of dispatching through dead state
• channel hints stay hints; plugins do not take raw provider or credential ownership

This is a host-mediated attachment seam, not a generic channel SDK.

What changed

• Added OpenClawPluginApi.sendSessionAttachment plus SDK exports for attachment params and results.
• Added host-side file validation, delivery-route lookup hardening, bundled-plugin enforcement, and stale-registry protection.
• Resolved relative file paths against the session agent workspace so real plugin callbacks do not fall back to the default host workspace.
• Added channel attachment hints from [plugin sdk] Add generic SDK seam followups #74483: caption-format precedence, Telegram silent/parse-mode/force-document hints, and Slack thread targeting.
• Plumbed parseMode through outbound message formatting and the Telegram direct/gateway adapters.
• Re-exported Telegram formatting helpers for plugin authors that need Telegram-safe captions.
• Preserved the loader's closed-after-register guard for registration-only APIs, but kept sendSessionAttachment callable after register() so a real bundled plugin can capture it during registration and invoke it later from a live callback or handler.
• Added focused contract and loader regression coverage for stale-registry protection, workspace-relative resolution, direct route dispatch, and post-registration late calls.

Relationship to adjacent seams

This does not try to solve scheduling, session actions, session projection, or run-context lifecycle. It is deliberately narrower: one host-mediated path for delivering plugin-owned files through the active session route.

Non-goals

• Does not give plugins direct Telegram, Slack, or Discord delivery ownership.
• Does not add arbitrary channel broadcast or free-form outbound routing.
• Does not include scheduled turns, session actions, derived path facts, SessionEntry projection, finalize retry/run-context lifecycle, or advanced workflow composition fixtures.
• Does not claim to close broader Control UI/native-page RFC scope; this only adds the generic attachment delivery seam.

Stack context

• Predecessors: [plugin sdk] Consolidate workflow seams and fixtures #73384, [plugin sdk] Add generic SDK seam followups #74483
• Docs split: [docs][plugin sdk] Split host-hook recipes from workflow follow-ups #74853
• Foundation: [plugin sdk] Add generic plugin host-hook contracts #72287

Real behavior proof

Behavior or issue addressed:
This fixes the narrow host-mediated attachment seam without broadening it into direct channel ownership. Before these follow-up fixes, a captured sendSessionAttachment closure could be closed accidentally by the loader guard, relative attachment paths could resolve against the wrong workspace, and Telegram media captions could be forced through the HTML path even when HTML was not explicitly requested. After this patch, the loader keeps sendSessionAttachment callable after register(), the host resolves relative paths against the session agent workspace, and the active direct-outbound route receives the validated file plus caption text.

Real environment tested:
Standalone runtime proof from /Users/lume/openclaw-review-worktrees/pr-75581-rebase using a live session store, an agent workspace rooted in a fresh temp state directory, and a direct outbound proof channel registered in the active plugin registry.

Exact steps or command run after this patch:

node --import tsx <<'NODE'
import fs from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import { updateSessionStore } from './src/config/sessions.js';
import { sendPluginSessionAttachment } from './src/plugins/host-hook-workflow.js';
import { setActivePluginRegistry, getActivePluginRegistry } from './src/plugins/runtime.js';
import { createTestRegistry } from './src/test-utils/channel-plugins.js';

const previousRegistry = getActivePluginRegistry();
const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openclaw-pr75581-proof-'));
const workspaceDir = path.join(stateDir, 'workspace');
const storePath = path.join(stateDir, 'sessions.json');
await fs.mkdir(workspaceDir, { recursive: true });
await fs.writeFile(path.join(workspaceDir, 'proof-report.txt'), 'proof attachment body\n', 'utf8');
await updateSessionStore(storePath, (store) => {
  store['agent:main:main'] = {
    sessionId: 'session-id',
    updatedAt: Date.now(),
    deliveryContext: { channel: 'proofchat', to: '12345', accountId: 'default' },
  };
  return undefined;
});
const deliveries = [];
setActivePluginRegistry(
  createTestRegistry([
    {
      pluginId: 'proofchat',
      source: 'proof',
      plugin: {
        id: 'proofchat',
        meta: {
          id: 'proofchat',
          label: 'Proof Chat',
          selectionLabel: 'Proof Chat',
          docsPath: '/channels/proofchat',
          blurb: 'proof direct channel',
        },
        capabilities: { chatTypes: ['direct'] },
        config: {
          listAccountIds: () => ['default'],
          resolveAccount: () => ({ accountId: 'default' }),
        },
        outbound: {
          deliveryMode: 'direct',
          sendText: async ({ to, text, accountId }) => {
            deliveries.push({ to, text, mediaUrl: null, accountId: accountId ?? null });
            return { channel: 'proofchat', messageId: 'proof-text-1' };
          },
          sendMedia: async ({ to, text, mediaUrl, accountId }) => {
            deliveries.push({ to, text, mediaUrl: mediaUrl ?? null, accountId: accountId ?? null });
            return { channel: 'proofchat', messageId: 'proof-media-1' };
          },
        },
      },
    },
  ]),
);

const result = await sendPluginSessionAttachment({
  origin: 'bundled',
  sessionKey: 'agent:main:main',
  files: [{ path: './proof-report.txt' }],
  text: 'attachment ready',
  config: {
    session: { store: storePath },
    agents: { list: [{ id: 'main', workspace: workspaceDir }] },
  },
});
console.log(JSON.stringify({ result, deliveries }, null, 2));
setActivePluginRegistry(previousRegistry);
NODE

Evidence after fix:

{
  "result": {
    "ok": true,
    "channel": "proofchat",
    "deliveredTo": "12345",
    "count": 1
  },
  "deliveries": [
    {
      "to": "12345",
      "text": "attachment ready",
      "mediaUrl": "/var/folders/l7/tyvn8qfs50v57w__75s3k0f00000gp/T/openclaw-pr75581-proof-pHeAVB/workspace/proof-report.txt",
      "accountId": "default"
    }
  ]
}

Observed result after fix:
The bundled-only attachment dispatch succeeds, the relative attachment path resolves against the session agent workspace instead of falling back to the default host workspace, and the active direct-outbound route receives the resolved file plus caption text. The loader regression is also covered on this head by pnpm test src/plugins/loader.test.ts, which proves sendSessionAttachment stays callable after register() while registration-only APIs still close.

What was not tested:
This proof did not exercise a full external Telegram/Slack/Discord live account or an end-to-end GUI flow. The runtime proof here is intentionally limited to real host validation, session-route lookup, workspace-relative path resolution, and direct outbound attachment dispatch inside a live OpenClaw runtime.

Validation

• pnpm test src/plugins/loader.test.ts
• pnpm test src/config/sessions/delivery-info.test.ts src/plugins/contracts/session-attachments.contract.test.ts extensions/telegram/api.test.ts extensions/telegram/src/outbound-adapter.test.ts extensions/telegram/src/channel.gateway.test.ts
• pnpm plugin-sdk:api:check
• pnpm lint:core
• pnpm lint:extensions
• git diff --check