inbound turn
  └─ context.collect    plugins contribute PromptContribution blocks
  └─ context.project    contributions projected into the outgoing message list
  └─ (model call)
  └─ context.prune      token-pressure pruning (in-memory, per turn)
  └─ compaction.plan    summarisation planning (persists to the transcript)

import type { PromptContribution } from "openclaw/plugin-sdk";

const contribution: PromptContribution = {
  // Context blocks, merged by placement field and sorted by priority (desc, stable):
  prependSystemPrompt: [],   // before the built system prompt
  systemPrompt: undefined,   // plain string — last writer wins on merge
  appendSystemPrompt: [],    // after the built system prompt
  prependContext: [],        // before the user turn
  appendContext: [],         // after the user turn
  prependBeforeMetadata: [], // before the metadata block group
  injectAfterMetadata: [],   // after the metadata block group
  appendAfterUserMessage: [],// after the clean user message
  metadata: [],              // metadata lane blocks
  pluginData: {},            // merged into stored entries for later reads
};

type ContextBlock = {
  id?: string;
  source: string;          // your plugin id — label for /context reporting
  text: string;
  priority?: number;       // higher sorts earlier within a placement field
  tokenEstimate?: number;
  metadata?: Record<string, unknown>;
};

type ContextLifecycleContext = {
  agentId?: string;
  sessionId: string;
  sessionKey?: string;
  runId?: string;            // stable across retries within the turn
  workspaceDir?: string;
  trigger?: string;          // "user" | "heartbeat" | "cron" | "steer" | "memory" | "internal"
  channelId?: string;
  modelId?: string;
  provider?: string;
  tokenWindow?: { modelId: string; provider: string; contextWindowTokens?: number; reservedOutputTokens?: number; estimatedInputTokens?: number };
  usage?: { input?: number; output?: number; cacheRead?: number; cacheWrite?: number; total?: number };
  storageCursor?: { backend: "fs-jsonl" | "sqlite" | "postgres"; sessionId: string; seq?: number; entryId?: string; /* ... */ };
  turnNumber?: number;       // completed user-message turns; DB backends only
  sessionCreatedAt?: Date;   // DB backends only
  runtimeIdentity?: PluginRuntimeIdentity;
  turn?: PluginTurnIdentity;
};

import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk";

export default {
  name: "my-compactor",
  ownsCompaction: true,   // runtime skips its built-in compaction trigger
  async register(api) {
    api.on("context.prune", (event) => {
      // your pruning policy; returning compactionHandled is redundant here
      return { messages: event.messages.slice(-20) };
    });
    api.on("compaction.plan", (event) => {
      // your summarisation planning
    });
  },
} satisfies OpenClawPluginDefinition;

api.on("context.collect", async (event) => {
  const big = await fetchExternalGraph(event.prompt); // network call on the critical path
  return { appendContext: [{ source: "my-plugin", text: big }] };
});