ofiere-openclaw-plugin 4.54.1 → 4.55.0

package/src/attachments.ts

@@ -1,601 +1,601 @@
-// src/attachments.ts — Plugin-side SOP/Framework attachment plumbing.
-// Three responsibilities:
-//   1. before_prompt_build hook: read the most-recent conversation for the
-//      caller's agent and inject any attached SOPs/Frameworks as system
-//      context (cached per-agent like the brain hook).
-//   2. propose_attach: validate target tier + doc kind, return token-cost
-//      summary + HMAC confirmation token (5 min ttl).
-//   3. commit_attach: re-verify token, write attachment ids to the row.
-
-import type { SupabaseClient } from "@supabase/supabase-js";
-import { renderAttachmentBlock } from "./sop-render.js";
-import {
-  resolveTargetTier,
-  isDocKindValidForTier,
-  invalidateAgentTier,
-} from "./agent-tier.js";
-import { issueAttachmentToken, verifyAttachmentToken } from "./attach-token.js";
-import { loadSubagentRow, buildStaffPersonaBlock, readDispatchSubagentId, loadChiefStaffDefaults, loadChiefAgentConfig, loadDispatchContextBySession, resolveStaffModels, type SubagentRow, type DispatchContextRow } from "./staffPersona.js";
-
-interface ToolResult {
-  content: Array<{ type: "text"; text: string }>;
-}
-function ok(data: unknown): ToolResult {
-  return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
-}
-function err(message: string): ToolResult {
-  return { content: [{ type: "text" as const, text: `Error: ${message}` }] };
-}
-
-export type TargetKind = "conversation" | "task" | "scheduler_event" | "subagent";
-export type DocKind = "sop" | "framework";
-
-const VALID_TARGETS: ReadonlyArray<TargetKind> = ["conversation", "task", "scheduler_event", "subagent"];
-function isValidTargetKind(v: unknown): v is TargetKind {
-  return typeof v === "string" && (VALID_TARGETS as readonly string[]).includes(v);
-}
-
-// ── Token cost (char/4 heuristic, matches dashboard) ──
-function estimateTokens(content: unknown): number {
-  if (content == null) return 0;
-  const str = typeof content === "string" ? content : JSON.stringify(content);
-  return Math.ceil(str.length / 4);
-}
-
-// ── Attachment write logic ──
-async function applyAttachmentWrite(args: {
-  supabase: SupabaseClient;
-  userId: string;
-  targetKind: TargetKind;
-  targetId: string;
-  docKind: DocKind;
-  docIds: string[];
-}): Promise<{ ok: boolean; error?: string }> {
-  const { supabase, userId, targetKind, targetId, docKind, docIds } = args;
-  if (!docIds.length) return { ok: true };
-
-  if (targetKind === "conversation") {
-    const col = docKind === "sop" ? "attached_sop_ids" : "attached_framework_ids";
-    const { data: cur, error: readErr } = await supabase
-      .from("conversations")
-      .select(col)
-      .eq("user_id", userId)
-      .eq("id", targetId)
-      .maybeSingle();
-    if (readErr) return { ok: false, error: readErr.message };
-    const existing = ((cur as Record<string, string[] | undefined> | null)?.[col]) || [];
-    const merged = Array.from(new Set([...existing, ...docIds]));
-    const { error: writeErr } = await supabase
-      .from("conversations")
-      .update({ [col]: merged, updated_at: new Date().toISOString() })
-      .eq("user_id", userId)
-      .eq("id", targetId);
-    if (writeErr) return { ok: false, error: writeErr.message };
-    return { ok: true };
-  }
-
-  if (targetKind === "task" || targetKind === "scheduler_event") {
-    const tbl = targetKind === "task" ? "tasks" : "scheduler_events";
-    const fieldKey = docKind === "sop" ? "sop_ids" : "framework_ids";
-    const { data: cur, error: readErr } = await supabase
-      .from(tbl)
-      .select("custom_fields")
-      .eq("user_id", userId)
-      .eq("id", targetId)
-      .maybeSingle();
-    if (readErr) return { ok: false, error: readErr.message };
-    const cf = (cur?.custom_fields as Record<string, unknown> | null) || {};
-    const existing: string[] = Array.isArray(cf?.[fieldKey]) ? (cf[fieldKey] as string[]) : [];
-    const merged = Array.from(new Set([...existing, ...docIds]));
-    const nextCf = { ...cf, [fieldKey]: merged };
-    const { error: writeErr } = await supabase
-      .from(tbl)
-      .update({ custom_fields: nextCf, updated_at: new Date().toISOString() })
-      .eq("user_id", userId)
-      .eq("id", targetId);
-    if (writeErr) return { ok: false, error: writeErr.message };
-    return { ok: true };
-  }
-
-  // Cycle 11 — subagent target_kind. Writes profile-level defaults that apply
-  // across EVERY dispatch to the staff (unioned with per-task ids at dispatch
-  // time in task-dispatcher edge fn via loadStaffDefaultAttachments).
-  if (targetKind === "subagent") {
-    const col = docKind === "sop" ? "attached_sop_ids" : "attached_framework_ids";
-    const { data: cur, error: readErr } = await supabase
-      .from("agent_subagents")
-      .select(col)
-      .eq("user_id", userId)
-      .eq("id", targetId)
-      .maybeSingle();
-    if (readErr) return { ok: false, error: readErr.message };
-    const existing = ((cur as Record<string, string[] | undefined> | null)?.[col]) || [];
-    const merged = Array.from(new Set([...existing, ...docIds]));
-    const { error: writeErr } = await supabase
-      .from("agent_subagents")
-      .update({ [col]: merged })
-      .eq("user_id", userId)
-      .eq("id", targetId);
-    if (writeErr) return { ok: false, error: writeErr.message };
-    return { ok: true };
-  }
-
-  return { ok: false, error: "unsupported target_kind" };
-}
-
-// ── Load target row identity (chief agent + optional subagent) for tier check ──
-interface TargetIdentity {
-  agentId: string | null;
-  subagentId: string | null;
-}
-
-async function loadTargetIdentity(args: {
-  supabase: SupabaseClient;
-  userId: string;
-  targetKind: TargetKind;
-  targetId: string;
-}): Promise<TargetIdentity | null> {
-  const { supabase, userId, targetKind, targetId } = args;
-  // Cycle 11 — subagent target: identity is { agentId: chief_agent_id, subagentId: row.id }.
-  // resolveTargetTier sees subagentId set → returns "staff" tier without a chief lookup.
-  if (targetKind === "subagent") {
-    const { data } = await supabase
-      .from("agent_subagents")
-      .select("id, chief_agent_id")
-      .eq("user_id", userId)
-      .eq("id", targetId)
-      .maybeSingle();
-    if (!data) return null;
-    return {
-      agentId: (data.chief_agent_id as string | null) ?? null,
-      subagentId: (data.id as string | null) ?? null,
-    };
-  }
-  const tbl =
-    targetKind === "conversation" ? "conversations" :
-    targetKind === "task" ? "tasks" : "scheduler_events";
-  const { data } = await supabase
-    .from(tbl)
-    .select("agent_id, subagent_id")
-    .eq("user_id", userId)
-    .eq("id", targetId)
-    .maybeSingle();
-  if (!data) return null;
-  return {
-    agentId: (data.agent_id as string | null) ?? null,
-    subagentId: (data.subagent_id as string | null) ?? null,
-  };
-}
-
-// ── Validate that every doc id belongs to userId in the right table ──
-async function validateDocIds(args: {
-  supabase: SupabaseClient;
-  userId: string;
-  docKind: DocKind;
-  docIds: string[];
-}): Promise<{ ok: boolean; matched: string[] }> {
-  const { supabase, userId, docKind, docIds } = args;
-  if (!docIds.length) return { ok: true, matched: [] };
-  const tbl = docKind === "sop" ? "agent_sops" : "frameworks";
-  const { data } = await supabase
-    .from(tbl)
-    .select("id")
-    .eq("user_id", userId)
-    .in("id", docIds);
-  const matched = (data || []).map((r: { id: string }) => r.id);
-  return { ok: matched.length === docIds.length, matched };
-}
-
-// ── propose_attach: validate + compute cost + issue token ──
-export async function handleProposeAttach(args: {
-  supabase: SupabaseClient;
-  userId: string;
-  docKind: DocKind;
-  params: Record<string, unknown>;
-}): Promise<ToolResult> {
-  const { supabase, userId, docKind, params } = args;
-  if (!isValidTargetKind(params.target_kind)) {
-    return err("Invalid target_kind. Use one of: conversation, task, scheduler_event");
-  }
-  const targetKind = params.target_kind as TargetKind;
-  const targetId = params.target_id as string;
-  if (!targetId) return err("Missing target_id");
-  if (!Array.isArray(params.doc_ids) || params.doc_ids.length === 0) {
-    return err("Missing doc_ids[]");
-  }
-  const docIds = (params.doc_ids as unknown[]).filter(
-    (x): x is string => typeof x === "string",
-  );
-
-  const identity = await loadTargetIdentity({
-    supabase, userId, targetKind, targetId,
-  });
-  if (!identity || (!identity.agentId && !identity.subagentId)) {
-    return err("target_not_found_or_no_agent");
-  }
-
-  const tierResolution = await resolveTargetTier(supabase, identity, userId);
-  if (!tierResolution.tier) {
-    return err("agent_unclassified — set tier in dashboard agent settings or via override");
-  }
-  if (!isDocKindValidForTier(docKind, tierResolution.tier)) {
-    return err(
-      `tier_mismatch — assigned agent is ${tierResolution.tier}; ` +
-      (docKind === "sop"
-        ? "SOPs only attach to staff"
-        : "Frameworks only attach to c-suite"),
-    );
-  }
-
-  const v = await validateDocIds({ supabase, userId, docKind, docIds });
-  if (!v.ok) return err("unknown_doc — one or more doc_ids do not belong to you");
-
-  // Cost summary
-  const tbl = docKind === "sop" ? "agent_sops" : "frameworks";
-  const { data: rows } = await supabase
-    .from(tbl)
-    .select("id, title, content")
-    .eq("user_id", userId)
-    .in("id", docIds);
-  const breakdown = (rows || []).map((r: { id: string; title: string; content: string }) => ({
-    id: r.id,
-    title: r.title || (docKind === "sop" ? "Untitled SOP" : "Untitled Framework"),
-    tokens: estimateTokens(r.content),
-    kind: docKind,
-  }));
-  const totalTokens = breakdown.reduce((acc, b) => acc + b.tokens, 0);
-
-  let token: string;
-  try {
-    token = issueAttachmentToken({
-      userId, targetKind, targetId, docKind, docIds,
-    });
-  } catch (e) {
-    return err(`token_issue_failed: ${e instanceof Error ? e.message : String(e)}`);
-  }
-
-  const noun = docKind === "sop" ? "SOP" : "Framework";
-  const plural = docIds.length === 1 ? noun : `${noun}s`;
-  const summary = `Adding ${docIds.length} ${plural} (~${totalTokens.toLocaleString()} tokens) to ${targetKind} ${targetId}.`;
-
-  return ok({
-    requires_confirmation: true,
-    target_kind: targetKind,
-    target_id: targetId,
-    doc_kind: docKind,
-    doc_ids: docIds,
-    tier: tierResolution.tier,
-    tier_source: tierResolution.source,
-    token_cost: totalTokens,
-    breakdown,
-    confirmation_token: token,
-    confirmation_prompt:
-      `${summary} Ask the user: "Proceed? (~${totalTokens.toLocaleString()} tokens)" — only call commit_attach AFTER user approves.`,
-  });
-}
-
-// ── commit_attach: verify token + write ──
-export async function handleCommitAttach(args: {
-  supabase: SupabaseClient;
-  userId: string;
-  docKind: DocKind;
-  params: Record<string, unknown>;
-}): Promise<ToolResult> {
-  const { supabase, userId, docKind, params } = args;
-  if (!isValidTargetKind(params.target_kind)) return err("Invalid target_kind");
-  const targetKind = params.target_kind as TargetKind;
-  const targetId = params.target_id as string;
-  if (!targetId) return err("Missing target_id");
-  if (!Array.isArray(params.doc_ids) || params.doc_ids.length === 0) {
-    return err("Missing doc_ids[]");
-  }
-  const docIds = (params.doc_ids as unknown[]).filter(
-    (x): x is string => typeof x === "string",
-  );
-  const token = params.confirmation_token as string;
-  if (!token) return err("Missing confirmation_token (call propose_attach first)");
-
-  const v = verifyAttachmentToken({
-    token, userId, targetKind, targetId, docKind, docIds,
-  });
-  if (!v.ok) return err(`token_${v.reason}`);
-
-  const wr = await applyAttachmentWrite({
-    supabase, userId, targetKind, targetId, docKind, docIds,
-  });
-  if (!wr.ok) return err(wr.error || "write_failed");
-
-  // Invalidate the per-agent attachment cache so the next prompt build picks up the new ids
-  attachmentCache.clear();
-
-  return ok({
-    ok: true,
-    attached: docIds.length,
-    target_kind: targetKind,
-    target_id: targetId,
-    doc_kind: docKind,
-  });
-}
-
-// ── before_prompt_build hook ──
-const attachmentCache = new Map<string, { text: string; at: number }>();
-const ATTACH_CACHE_TTL_MS = 600_000;
-const ATTACH_CACHE_STALE_MS = 900_000;
-
-function isSystemName(name: string): boolean {
-  const s = name.toLowerCase().trim();
-  return s === "" || s === "ofiere" || s === "openclaw" || s === "system" || s === "plugin" || s === "gateway" || s.includes("plugin");
-}
-
-// Render a block from explicit doc-id lists. Used by both the dispatch-params
-// path (when workflow/task-dispatcher hands ids in via ctx) and the conversation
-// fallback path (when no explicit ids are present).
-async function renderBlockForIds(args: {
-  supabase: SupabaseClient;
-  userId: string;
-  sopIds: string[];
-  fwIds: string[];
-}): Promise<string> {
-  const { supabase, userId, sopIds, fwIds } = args;
-  if (!sopIds.length && !fwIds.length) return "";
-
-  const [sopsRes, fwsRes] = await Promise.all([
-    sopIds.length
-      ? supabase
-          .from("agent_sops")
-          .select("title, content")
-          .eq("user_id", userId)
-          .in("id", sopIds)
-      : Promise.resolve({ data: [] as Array<{ title: string; content: string }> }),
-    fwIds.length
-      ? supabase
-          .from("frameworks")
-          .select("title, content")
-          .eq("user_id", userId)
-          .in("id", fwIds)
-      : Promise.resolve({ data: [] as Array<{ title: string; content: string }> }),
-  ]);
-
-  const sops = (sopsRes.data || []).map((s) => ({
-    title: s.title || "Untitled SOP",
-    content: typeof s.content === "string" ? s.content : JSON.stringify(s.content ?? ""),
-  }));
-  const frameworks = (fwsRes.data || []).map((f) => ({
-    title: f.title || "Untitled Framework",
-    content: typeof f.content === "string" ? f.content : JSON.stringify(f.content ?? ""),
-  }));
-
-  return renderAttachmentBlock({ sops, frameworks });
-}
-
-// Pluck attachment ids from the `before_prompt_build` ctx. Exact path varies by
-// the dispatch surface that fires the prompt build, so we probe several known
-// locations. Workflow executor + task-dispatcher edge function both stash ids
-// under `metadata` on their request frames.
-function readDispatchAttachmentIds(ctx: any): { sopIds: string[]; fwIds: string[] } {
-  const candidates: Array<Record<string, unknown> | undefined> = [
-    ctx?.metadata,
-    ctx?.params?.metadata,
-    ctx?.payload?.metadata,
-    ctx?.request?.metadata,
-    ctx?.options?.metadata,
-    ctx, // last resort: top level
-  ];
-  for (const c of candidates) {
-    if (!c || typeof c !== "object") continue;
-    const sop = (c as any).attached_sop_ids;
-    const fw = (c as any).attached_framework_ids;
-    if (Array.isArray(sop) || Array.isArray(fw)) {
-      return {
-        sopIds: Array.isArray(sop) ? sop.filter((x: unknown): x is string => typeof x === "string") : [],
-        fwIds: Array.isArray(fw) ? fw.filter((x: unknown): x is string => typeof x === "string") : [],
-      };
-    }
-  }
-  return { sopIds: [], fwIds: [] };
-}
-
-async function buildAttachmentBlock(args: {
-  supabase: SupabaseClient;
-  userId: string;
-  agentId: string;
-  subagentId?: string | null;
-}): Promise<string> {
-  const { supabase, userId, agentId, subagentId } = args;
-
-  // When a staff dispatch arrives, prefer attachments scoped to the subagent
-  // so a chief and its staff never share an attachment surface implicitly.
-  if (subagentId) {
-    const { data: staffConv } = await supabase
-      .from("conversations")
-      .select("id, attached_sop_ids, attached_framework_ids")
-      .eq("user_id", userId)
-      .eq("agent_id", agentId)
-      .eq("subagent_id", subagentId)
-      .order("updated_at", { ascending: false })
-      .limit(1)
-      .maybeSingle();
-    if (staffConv) {
-      const sopIds: string[] = (staffConv.attached_sop_ids as string[] | null) || [];
-      const fwIds: string[] = (staffConv.attached_framework_ids as string[] | null) || [];
-      return renderBlockForIds({ supabase, userId, sopIds, fwIds });
-    }
-    // No staff-scoped conversation yet — fall through to chief-level lookup.
-  }
-
-  // Find the most recently active conversation for this agent. The dashboard
-  // bumps `updated_at` whenever a message is sent or attachments change, so
-  // this gives us the right run target most of the time.
-  const { data: convRow } = await supabase
-    .from("conversations")
-    .select("id, attached_sop_ids, attached_framework_ids")
-    .eq("user_id", userId)
-    .eq("agent_id", agentId)
-    .order("updated_at", { ascending: false })
-    .limit(1)
-    .maybeSingle();
-
-  const sopIds: string[] = (convRow?.attached_sop_ids as string[] | null) || [];
-  const fwIds: string[] = (convRow?.attached_framework_ids as string[] | null) || [];
-  return renderBlockForIds({ supabase, userId, sopIds, fwIds });
-}
-
-export function registerAttachmentContextHook(args: {
-  api: any;
-  supabase: SupabaseClient;
-  userId: string;
-  fallbackAgentId: string;
-  resolveAgent: (id?: string) => Promise<string | null>;
-}): void {
-  const { api, supabase, userId, fallbackAgentId, resolveAgent } = args;
-
-  try {
-    api.on("before_prompt_build", async (_event: any, ctx: any) => {
-      try {
-        const ctxAgentId = ctx?.agentId || "";
-        let resolvedAgentId = fallbackAgentId;
-        if (ctxAgentId && !isSystemName(ctxAgentId)) {
-          try {
-            const r = await resolveAgent(ctxAgentId);
-            if (r) resolvedAgentId = r;
-          } catch { /* fall through */ }
-        }
-        if (!resolvedAgentId) return;
-
-        // Cycle 7b — staff persona injection. Only fires when subagent_id is
-        // present in dispatch metadata (task-dispatcher / scheduler / explicit
-        // dispatch params). Plain user chats with the chief never persona-swap.
-        //
-        // Cycle 7b BUGSHOOT-1 (BUG 2) — OpenClaw gateway core rejects unknown
-        // root key `metadata` on chat.send, so the dispatcher can't ride
-        // metadata through the wire. After the metadata path comes up empty,
-        // try the dispatch_context table keyed by sessionKey. The metadata
-        // path is preferred so a future gateway upgrade keeps working.
-        const sessionKey: string | null =
-          ctx?.sessionKey || ctx?.session_key ||
-          (typeof _event === "object" ? (_event?.sessionKey || _event?.context?.sessionKey || null) : null) ||
-          null;
-        let dispatchCtxRow: DispatchContextRow | null = null;
-        let subagentId = readDispatchSubagentId(ctx);
-        if (!subagentId && sessionKey) {
-          dispatchCtxRow = await loadDispatchContextBySession(supabase, userId, sessionKey).catch(() => null);
-          if (dispatchCtxRow?.subagent_id) {
-            subagentId = dispatchCtxRow.subagent_id;
-            api.logger?.debug?.(
-              `[ofiere-staff] subagent_id resolved via dispatch_context (session=${sessionKey})`,
-            );
-          }
-        }
-        let staffPrefix = "";
-        let staffRow: SubagentRow | null = null;
-        if (subagentId) {
-          staffRow = await loadSubagentRow(supabase, userId, subagentId);
-          if (staffRow && staffRow.chief_agent_id === resolvedAgentId) {
-            const [chiefDefaults, chiefConfig] = await Promise.all([
-              loadChiefStaffDefaults(supabase, userId, staffRow.chief_agent_id).catch(() => null),
-              loadChiefAgentConfig(supabase, userId, staffRow.chief_agent_id).catch(() => null),
-            ]);
-            const resolved = resolveStaffModels(staffRow, chiefDefaults, chiefConfig);
-            staffPrefix = buildStaffPersonaBlock(staffRow, resolved) + "\n\n---\n\n";
-            api.logger?.debug?.(
-              `[ofiere-staff] subagent ${subagentId} (${staffRow.name}) reporting to ${resolvedAgentId} — persona injected; resolved models: ${JSON.stringify(resolved)}`,
-            );
-          } else if (staffRow) {
-            api.logger?.warn?.(
-              `[ofiere-staff] subagent ${subagentId} chief_mismatch (got ${staffRow.chief_agent_id}, expected ${resolvedAgentId}) — ignoring persona`,
-            );
-            staffRow = null;
-          } else {
-            api.logger?.warn?.(`[ofiere-staff] subagent ${subagentId} not found — ignoring persona`);
-          }
-        }
-
-        // wrap any return-block with the staff prefix (or pass through unchanged
-        // when no staff dispatch).
-        const wrap = (block: string | undefined | null): { appendSystemContext: string } | undefined => {
-          const finalBlock = staffPrefix + (block || "");
-          return finalBlock ? { appendSystemContext: finalBlock } : undefined;
-        };
-
-        // Dispatch-params path: workflow executor + task-dispatcher edge function
-        // can stash explicit `attached_sop_ids` / `attached_framework_ids` on the
-        // chat.send frame's metadata. When present, prefer them over the
-        // most-recent-conversation lookup and bypass cache (per-dispatch ids).
-        let dispatchIds = readDispatchAttachmentIds(ctx);
-        // Cycle 7b BUGSHOOT-1 (BUG 2) — DB-backed dispatch-context fallback for
-        // attachment ids. Same rationale as the subagent_id fallback above.
-        if (!dispatchIds.sopIds.length && !dispatchIds.fwIds.length && sessionKey) {
-          if (!dispatchCtxRow) {
-            dispatchCtxRow = await loadDispatchContextBySession(supabase, userId, sessionKey).catch(() => null);
-          }
-          if (dispatchCtxRow && (dispatchCtxRow.attached_sop_ids.length || dispatchCtxRow.attached_framework_ids.length)) {
-            dispatchIds = {
-              sopIds: dispatchCtxRow.attached_sop_ids,
-              fwIds: dispatchCtxRow.attached_framework_ids,
-            };
-            api.logger?.debug?.(
-              `[ofiere-attach] dispatch ids via dispatch_context (session=${sessionKey}) sops=${dispatchIds.sopIds.length} fws=${dispatchIds.fwIds.length}`,
-            );
-          }
-        }
-        if (dispatchIds.sopIds.length || dispatchIds.fwIds.length) {
-          api.logger?.debug?.(
-            `[ofiere-attach] dispatch ids agent=${resolvedAgentId} sops=${dispatchIds.sopIds.length} fws=${dispatchIds.fwIds.length}`,
-          );
-          const block = await renderBlockForIds({
-            supabase, userId,
-            sopIds: dispatchIds.sopIds,
-            fwIds: dispatchIds.fwIds,
-          });
-          return wrap(block);
-        }
-
-        // Staff-mode runs bypass the chief-level attachment cache so a chief
-        // and its staff never share a cached attachment block.
-        if (subagentId) {
-          const block = await buildAttachmentBlock({
-            supabase, userId, agentId: resolvedAgentId, subagentId,
-          });
-          return wrap(block);
-        }
-
-        // Multi-tenant: a single plugin process can serve multiple users — key
-        // by (userId, agentId) so User B never sees User A's cached block.
-        const cacheKey = `${userId}::${resolvedAgentId}`;
-        const cached = attachmentCache.get(cacheKey);
-        if (cached) {
-          const age = Date.now() - cached.at;
-          if (age < ATTACH_CACHE_TTL_MS) {
-            return wrap(cached.text);
-          }
-          if (age < ATTACH_CACHE_STALE_MS) {
-            // Refresh in background
-            (async () => {
-              try {
-                const fresh = await buildAttachmentBlock({ supabase, userId, agentId: resolvedAgentId });
-                attachmentCache.set(cacheKey, { text: fresh, at: Date.now() });
-              } catch { /* ignore */ }
-            })();
-            return wrap(cached.text);
-          }
-        }
-
-        const block = await buildAttachmentBlock({ supabase, userId, agentId: resolvedAgentId });
-        attachmentCache.set(cacheKey, { text: block, at: Date.now() });
-        return wrap(block);
-      } catch (e) {
-        api.logger?.debug?.(`[ofiere-attach] before_prompt_build error: ${e instanceof Error ? e.message : e}`);
-      }
-    });
-  } catch {
-    api.logger?.debug?.("[ofiere] Could not register attachment context hook — appendSystemContext may not be supported");
-  }
-}
-
-// Public for tests / future hooks that need to drop the cache
-export function invalidateAttachmentCache(): void {
-  attachmentCache.clear();
-}
-
-// Re-export tier invalidation so callers don't need to import two modules
-export { invalidateAgentTier };
+// src/attachments.ts — Plugin-side SOP/Framework attachment plumbing.
+// Three responsibilities:
+//   1. before_prompt_build hook: read the most-recent conversation for the
+//      caller's agent and inject any attached SOPs/Frameworks as system
+//      context (cached per-agent like the brain hook).
+//   2. propose_attach: validate target tier + doc kind, return token-cost
+//      summary + HMAC confirmation token (5 min ttl).
+//   3. commit_attach: re-verify token, write attachment ids to the row.
+
+import type { SupabaseClient } from "@supabase/supabase-js";
+import { renderAttachmentBlock } from "./sop-render.js";
+import {
+  resolveTargetTier,
+  isDocKindValidForTier,
+  invalidateAgentTier,
+} from "./agent-tier.js";
+import { issueAttachmentToken, verifyAttachmentToken } from "./attach-token.js";
+import { loadSubagentRow, buildStaffPersonaBlock, readDispatchSubagentId, loadChiefStaffDefaults, loadChiefAgentConfig, loadDispatchContextBySession, resolveStaffModels, type SubagentRow, type DispatchContextRow } from "./staffPersona.js";
+
+interface ToolResult {
+  content: Array<{ type: "text"; text: string }>;
+}
+function ok(data: unknown): ToolResult {
+  return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+}
+function err(message: string): ToolResult {
+  return { content: [{ type: "text" as const, text: `Error: ${message}` }] };
+}
+
+export type TargetKind = "conversation" | "task" | "scheduler_event" | "subagent";
+export type DocKind = "sop" | "framework";
+
+const VALID_TARGETS: ReadonlyArray<TargetKind> = ["conversation", "task", "scheduler_event", "subagent"];
+function isValidTargetKind(v: unknown): v is TargetKind {
+  return typeof v === "string" && (VALID_TARGETS as readonly string[]).includes(v);
+}
+
+// ── Token cost (char/4 heuristic, matches dashboard) ──
+function estimateTokens(content: unknown): number {
+  if (content == null) return 0;
+  const str = typeof content === "string" ? content : JSON.stringify(content);
+  return Math.ceil(str.length / 4);
+}
+
+// ── Attachment write logic ──
+async function applyAttachmentWrite(args: {
+  supabase: SupabaseClient;
+  userId: string;
+  targetKind: TargetKind;
+  targetId: string;
+  docKind: DocKind;
+  docIds: string[];
+}): Promise<{ ok: boolean; error?: string }> {
+  const { supabase, userId, targetKind, targetId, docKind, docIds } = args;
+  if (!docIds.length) return { ok: true };
+
+  if (targetKind === "conversation") {
+    const col = docKind === "sop" ? "attached_sop_ids" : "attached_framework_ids";
+    const { data: cur, error: readErr } = await supabase
+      .from("conversations")
+      .select(col)
+      .eq("user_id", userId)
+      .eq("id", targetId)
+      .maybeSingle();
+    if (readErr) return { ok: false, error: readErr.message };
+    const existing = ((cur as Record<string, string[] | undefined> | null)?.[col]) || [];
+    const merged = Array.from(new Set([...existing, ...docIds]));
+    const { error: writeErr } = await supabase
+      .from("conversations")
+      .update({ [col]: merged, updated_at: new Date().toISOString() })
+      .eq("user_id", userId)
+      .eq("id", targetId);
+    if (writeErr) return { ok: false, error: writeErr.message };
+    return { ok: true };
+  }
+
+  if (targetKind === "task" || targetKind === "scheduler_event") {
+    const tbl = targetKind === "task" ? "tasks" : "scheduler_events";
+    const fieldKey = docKind === "sop" ? "sop_ids" : "framework_ids";
+    const { data: cur, error: readErr } = await supabase
+      .from(tbl)
+      .select("custom_fields")
+      .eq("user_id", userId)
+      .eq("id", targetId)
+      .maybeSingle();
+    if (readErr) return { ok: false, error: readErr.message };
+    const cf = (cur?.custom_fields as Record<string, unknown> | null) || {};
+    const existing: string[] = Array.isArray(cf?.[fieldKey]) ? (cf[fieldKey] as string[]) : [];
+    const merged = Array.from(new Set([...existing, ...docIds]));
+    const nextCf = { ...cf, [fieldKey]: merged };
+    const { error: writeErr } = await supabase
+      .from(tbl)
+      .update({ custom_fields: nextCf, updated_at: new Date().toISOString() })
+      .eq("user_id", userId)
+      .eq("id", targetId);
+    if (writeErr) return { ok: false, error: writeErr.message };
+    return { ok: true };
+  }
+
+  // Cycle 11 — subagent target_kind. Writes profile-level defaults that apply
+  // across EVERY dispatch to the staff (unioned with per-task ids at dispatch
+  // time in task-dispatcher edge fn via loadStaffDefaultAttachments).
+  if (targetKind === "subagent") {
+    const col = docKind === "sop" ? "attached_sop_ids" : "attached_framework_ids";
+    const { data: cur, error: readErr } = await supabase
+      .from("agent_subagents")
+      .select(col)
+      .eq("user_id", userId)
+      .eq("id", targetId)
+      .maybeSingle();
+    if (readErr) return { ok: false, error: readErr.message };
+    const existing = ((cur as Record<string, string[] | undefined> | null)?.[col]) || [];
+    const merged = Array.from(new Set([...existing, ...docIds]));
+    const { error: writeErr } = await supabase
+      .from("agent_subagents")
+      .update({ [col]: merged })
+      .eq("user_id", userId)
+      .eq("id", targetId);
+    if (writeErr) return { ok: false, error: writeErr.message };
+    return { ok: true };
+  }
+
+  return { ok: false, error: "unsupported target_kind" };
+}
+
+// ── Load target row identity (chief agent + optional subagent) for tier check ──
+interface TargetIdentity {
+  agentId: string | null;
+  subagentId: string | null;
+}
+
+async function loadTargetIdentity(args: {
+  supabase: SupabaseClient;
+  userId: string;
+  targetKind: TargetKind;
+  targetId: string;
+}): Promise<TargetIdentity | null> {
+  const { supabase, userId, targetKind, targetId } = args;
+  // Cycle 11 — subagent target: identity is { agentId: chief_agent_id, subagentId: row.id }.
+  // resolveTargetTier sees subagentId set → returns "staff" tier without a chief lookup.
+  if (targetKind === "subagent") {
+    const { data } = await supabase
+      .from("agent_subagents")
+      .select("id, chief_agent_id")
+      .eq("user_id", userId)
+      .eq("id", targetId)
+      .maybeSingle();
+    if (!data) return null;
+    return {
+      agentId: (data.chief_agent_id as string | null) ?? null,
+      subagentId: (data.id as string | null) ?? null,
+    };
+  }
+  const tbl =
+    targetKind === "conversation" ? "conversations" :
+    targetKind === "task" ? "tasks" : "scheduler_events";
+  const { data } = await supabase
+    .from(tbl)
+    .select("agent_id, subagent_id")
+    .eq("user_id", userId)
+    .eq("id", targetId)
+    .maybeSingle();
+  if (!data) return null;
+  return {
+    agentId: (data.agent_id as string | null) ?? null,
+    subagentId: (data.subagent_id as string | null) ?? null,
+  };
+}
+
+// ── Validate that every doc id belongs to userId in the right table ──
+async function validateDocIds(args: {
+  supabase: SupabaseClient;
+  userId: string;
+  docKind: DocKind;
+  docIds: string[];
+}): Promise<{ ok: boolean; matched: string[] }> {
+  const { supabase, userId, docKind, docIds } = args;
+  if (!docIds.length) return { ok: true, matched: [] };
+  const tbl = docKind === "sop" ? "agent_sops" : "frameworks";
+  const { data } = await supabase
+    .from(tbl)
+    .select("id")
+    .eq("user_id", userId)
+    .in("id", docIds);
+  const matched = (data || []).map((r: { id: string }) => r.id);
+  return { ok: matched.length === docIds.length, matched };
+}
+
+// ── propose_attach: validate + compute cost + issue token ──
+export async function handleProposeAttach(args: {
+  supabase: SupabaseClient;
+  userId: string;
+  docKind: DocKind;
+  params: Record<string, unknown>;
+}): Promise<ToolResult> {
+  const { supabase, userId, docKind, params } = args;
+  if (!isValidTargetKind(params.target_kind)) {
+    return err("Invalid target_kind. Use one of: conversation, task, scheduler_event");
+  }
+  const targetKind = params.target_kind as TargetKind;
+  const targetId = params.target_id as string;
+  if (!targetId) return err("Missing target_id");
+  if (!Array.isArray(params.doc_ids) || params.doc_ids.length === 0) {
+    return err("Missing doc_ids[]");
+  }
+  const docIds = (params.doc_ids as unknown[]).filter(
+    (x): x is string => typeof x === "string",
+  );
+
+  const identity = await loadTargetIdentity({
+    supabase, userId, targetKind, targetId,
+  });
+  if (!identity || (!identity.agentId && !identity.subagentId)) {
+    return err("target_not_found_or_no_agent");
+  }
+
+  const tierResolution = await resolveTargetTier(supabase, identity, userId);
+  if (!tierResolution.tier) {
+    return err("agent_unclassified — set tier in dashboard agent settings or via override");
+  }
+  if (!isDocKindValidForTier(docKind, tierResolution.tier)) {
+    return err(
+      `tier_mismatch — assigned agent is ${tierResolution.tier}; ` +
+      (docKind === "sop"
+        ? "SOPs only attach to staff"
+        : "Frameworks only attach to c-suite"),
+    );
+  }
+
+  const v = await validateDocIds({ supabase, userId, docKind, docIds });
+  if (!v.ok) return err("unknown_doc — one or more doc_ids do not belong to you");
+
+  // Cost summary
+  const tbl = docKind === "sop" ? "agent_sops" : "frameworks";
+  const { data: rows } = await supabase
+    .from(tbl)
+    .select("id, title, content")
+    .eq("user_id", userId)
+    .in("id", docIds);
+  const breakdown = (rows || []).map((r: { id: string; title: string; content: string }) => ({
+    id: r.id,
+    title: r.title || (docKind === "sop" ? "Untitled SOP" : "Untitled Framework"),
+    tokens: estimateTokens(r.content),
+    kind: docKind,
+  }));
+  const totalTokens = breakdown.reduce((acc, b) => acc + b.tokens, 0);
+
+  let token: string;
+  try {
+    token = issueAttachmentToken({
+      userId, targetKind, targetId, docKind, docIds,
+    });
+  } catch (e) {
+    return err(`token_issue_failed: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  const noun = docKind === "sop" ? "SOP" : "Framework";
+  const plural = docIds.length === 1 ? noun : `${noun}s`;
+  const summary = `Adding ${docIds.length} ${plural} (~${totalTokens.toLocaleString()} tokens) to ${targetKind} ${targetId}.`;
+
+  return ok({
+    requires_confirmation: true,
+    target_kind: targetKind,
+    target_id: targetId,
+    doc_kind: docKind,
+    doc_ids: docIds,
+    tier: tierResolution.tier,
+    tier_source: tierResolution.source,
+    token_cost: totalTokens,
+    breakdown,
+    confirmation_token: token,
+    confirmation_prompt:
+      `${summary} Ask the user: "Proceed? (~${totalTokens.toLocaleString()} tokens)" — only call commit_attach AFTER user approves.`,
+  });
+}
+
+// ── commit_attach: verify token + write ──
+export async function handleCommitAttach(args: {
+  supabase: SupabaseClient;
+  userId: string;
+  docKind: DocKind;
+  params: Record<string, unknown>;
+}): Promise<ToolResult> {
+  const { supabase, userId, docKind, params } = args;
+  if (!isValidTargetKind(params.target_kind)) return err("Invalid target_kind");
+  const targetKind = params.target_kind as TargetKind;
+  const targetId = params.target_id as string;
+  if (!targetId) return err("Missing target_id");
+  if (!Array.isArray(params.doc_ids) || params.doc_ids.length === 0) {
+    return err("Missing doc_ids[]");
+  }
+  const docIds = (params.doc_ids as unknown[]).filter(
+    (x): x is string => typeof x === "string",
+  );
+  const token = params.confirmation_token as string;
+  if (!token) return err("Missing confirmation_token (call propose_attach first)");
+
+  const v = verifyAttachmentToken({
+    token, userId, targetKind, targetId, docKind, docIds,
+  });
+  if (!v.ok) return err(`token_${v.reason}`);
+
+  const wr = await applyAttachmentWrite({
+    supabase, userId, targetKind, targetId, docKind, docIds,
+  });
+  if (!wr.ok) return err(wr.error || "write_failed");
+
+  // Invalidate the per-agent attachment cache so the next prompt build picks up the new ids
+  attachmentCache.clear();
+
+  return ok({
+    ok: true,
+    attached: docIds.length,
+    target_kind: targetKind,
+    target_id: targetId,
+    doc_kind: docKind,
+  });
+}
+
+// ── before_prompt_build hook ──
+const attachmentCache = new Map<string, { text: string; at: number }>();
+const ATTACH_CACHE_TTL_MS = 600_000;
+const ATTACH_CACHE_STALE_MS = 900_000;
+
+function isSystemName(name: string): boolean {
+  const s = name.toLowerCase().trim();
+  return s === "" || s === "ofiere" || s === "openclaw" || s === "system" || s === "plugin" || s === "gateway" || s.includes("plugin");
+}
+
+// Render a block from explicit doc-id lists. Used by both the dispatch-params
+// path (when workflow/task-dispatcher hands ids in via ctx) and the conversation
+// fallback path (when no explicit ids are present).
+async function renderBlockForIds(args: {
+  supabase: SupabaseClient;
+  userId: string;
+  sopIds: string[];
+  fwIds: string[];
+}): Promise<string> {
+  const { supabase, userId, sopIds, fwIds } = args;
+  if (!sopIds.length && !fwIds.length) return "";
+
+  const [sopsRes, fwsRes] = await Promise.all([
+    sopIds.length
+      ? supabase
+          .from("agent_sops")
+          .select("title, content")
+          .eq("user_id", userId)
+          .in("id", sopIds)
+      : Promise.resolve({ data: [] as Array<{ title: string; content: string }> }),
+    fwIds.length
+      ? supabase
+          .from("frameworks")
+          .select("title, content")
+          .eq("user_id", userId)
+          .in("id", fwIds)
+      : Promise.resolve({ data: [] as Array<{ title: string; content: string }> }),
+  ]);
+
+  const sops = (sopsRes.data || []).map((s) => ({
+    title: s.title || "Untitled SOP",
+    content: typeof s.content === "string" ? s.content : JSON.stringify(s.content ?? ""),
+  }));
+  const frameworks = (fwsRes.data || []).map((f) => ({
+    title: f.title || "Untitled Framework",
+    content: typeof f.content === "string" ? f.content : JSON.stringify(f.content ?? ""),
+  }));
+
+  return renderAttachmentBlock({ sops, frameworks });
+}
+
+// Pluck attachment ids from the `before_prompt_build` ctx. Exact path varies by
+// the dispatch surface that fires the prompt build, so we probe several known
+// locations. Workflow executor + task-dispatcher edge function both stash ids
+// under `metadata` on their request frames.
+function readDispatchAttachmentIds(ctx: any): { sopIds: string[]; fwIds: string[] } {
+  const candidates: Array<Record<string, unknown> | undefined> = [
+    ctx?.metadata,
+    ctx?.params?.metadata,
+    ctx?.payload?.metadata,
+    ctx?.request?.metadata,
+    ctx?.options?.metadata,
+    ctx, // last resort: top level
+  ];
+  for (const c of candidates) {
+    if (!c || typeof c !== "object") continue;
+    const sop = (c as any).attached_sop_ids;
+    const fw = (c as any).attached_framework_ids;
+    if (Array.isArray(sop) || Array.isArray(fw)) {
+      return {
+        sopIds: Array.isArray(sop) ? sop.filter((x: unknown): x is string => typeof x === "string") : [],
+        fwIds: Array.isArray(fw) ? fw.filter((x: unknown): x is string => typeof x === "string") : [],
+      };
+    }
+  }
+  return { sopIds: [], fwIds: [] };
+}
+
+async function buildAttachmentBlock(args: {
+  supabase: SupabaseClient;
+  userId: string;
+  agentId: string;
+  subagentId?: string | null;
+}): Promise<string> {
+  const { supabase, userId, agentId, subagentId } = args;
+
+  // When a staff dispatch arrives, prefer attachments scoped to the subagent
+  // so a chief and its staff never share an attachment surface implicitly.
+  if (subagentId) {
+    const { data: staffConv } = await supabase
+      .from("conversations")
+      .select("id, attached_sop_ids, attached_framework_ids")
+      .eq("user_id", userId)
+      .eq("agent_id", agentId)
+      .eq("subagent_id", subagentId)
+      .order("updated_at", { ascending: false })
+      .limit(1)
+      .maybeSingle();
+    if (staffConv) {
+      const sopIds: string[] = (staffConv.attached_sop_ids as string[] | null) || [];
+      const fwIds: string[] = (staffConv.attached_framework_ids as string[] | null) || [];
+      return renderBlockForIds({ supabase, userId, sopIds, fwIds });
+    }
+    // No staff-scoped conversation yet — fall through to chief-level lookup.
+  }
+
+  // Find the most recently active conversation for this agent. The dashboard
+  // bumps `updated_at` whenever a message is sent or attachments change, so
+  // this gives us the right run target most of the time.
+  const { data: convRow } = await supabase
+    .from("conversations")
+    .select("id, attached_sop_ids, attached_framework_ids")
+    .eq("user_id", userId)
+    .eq("agent_id", agentId)
+    .order("updated_at", { ascending: false })
+    .limit(1)
+    .maybeSingle();
+
+  const sopIds: string[] = (convRow?.attached_sop_ids as string[] | null) || [];
+  const fwIds: string[] = (convRow?.attached_framework_ids as string[] | null) || [];
+  return renderBlockForIds({ supabase, userId, sopIds, fwIds });
+}
+
+export function registerAttachmentContextHook(args: {
+  api: any;
+  supabase: SupabaseClient;
+  userId: string;
+  fallbackAgentId: string;
+  resolveAgent: (id?: string) => Promise<string | null>;
+}): void {
+  const { api, supabase, userId, fallbackAgentId, resolveAgent } = args;
+
+  try {
+    api.on("before_prompt_build", async (_event: any, ctx: any) => {
+      try {
+        const ctxAgentId = ctx?.agentId || "";
+        let resolvedAgentId = fallbackAgentId;
+        if (ctxAgentId && !isSystemName(ctxAgentId)) {
+          try {
+            const r = await resolveAgent(ctxAgentId);
+            if (r) resolvedAgentId = r;
+          } catch { /* fall through */ }
+        }
+        if (!resolvedAgentId) return;
+
+        // Cycle 7b — staff persona injection. Only fires when subagent_id is
+        // present in dispatch metadata (task-dispatcher / scheduler / explicit
+        // dispatch params). Plain user chats with the chief never persona-swap.
+        //
+        // Cycle 7b BUGSHOOT-1 (BUG 2) — OpenClaw gateway core rejects unknown
+        // root key `metadata` on chat.send, so the dispatcher can't ride
+        // metadata through the wire. After the metadata path comes up empty,
+        // try the dispatch_context table keyed by sessionKey. The metadata
+        // path is preferred so a future gateway upgrade keeps working.
+        const sessionKey: string | null =
+          ctx?.sessionKey || ctx?.session_key ||
+          (typeof _event === "object" ? (_event?.sessionKey || _event?.context?.sessionKey || null) : null) ||
+          null;
+        let dispatchCtxRow: DispatchContextRow | null = null;
+        let subagentId = readDispatchSubagentId(ctx);
+        if (!subagentId && sessionKey) {
+          dispatchCtxRow = await loadDispatchContextBySession(supabase, userId, sessionKey).catch(() => null);
+          if (dispatchCtxRow?.subagent_id) {
+            subagentId = dispatchCtxRow.subagent_id;
+            api.logger?.debug?.(
+              `[ofiere-staff] subagent_id resolved via dispatch_context (session=${sessionKey})`,
+            );
+          }
+        }
+        let staffPrefix = "";
+        let staffRow: SubagentRow | null = null;
+        if (subagentId) {
+          staffRow = await loadSubagentRow(supabase, userId, subagentId);
+          if (staffRow && staffRow.chief_agent_id === resolvedAgentId) {
+            const [chiefDefaults, chiefConfig] = await Promise.all([
+              loadChiefStaffDefaults(supabase, userId, staffRow.chief_agent_id).catch(() => null),
+              loadChiefAgentConfig(supabase, userId, staffRow.chief_agent_id).catch(() => null),
+            ]);
+            const resolved = resolveStaffModels(staffRow, chiefDefaults, chiefConfig);
+            staffPrefix = buildStaffPersonaBlock(staffRow, resolved) + "\n\n---\n\n";
+            api.logger?.debug?.(
+              `[ofiere-staff] subagent ${subagentId} (${staffRow.name}) reporting to ${resolvedAgentId} — persona injected; resolved models: ${JSON.stringify(resolved)}`,
+            );
+          } else if (staffRow) {
+            api.logger?.warn?.(
+              `[ofiere-staff] subagent ${subagentId} chief_mismatch (got ${staffRow.chief_agent_id}, expected ${resolvedAgentId}) — ignoring persona`,
+            );
+            staffRow = null;
+          } else {
+            api.logger?.warn?.(`[ofiere-staff] subagent ${subagentId} not found — ignoring persona`);
+          }
+        }
+
+        // wrap any return-block with the staff prefix (or pass through unchanged
+        // when no staff dispatch).
+        const wrap = (block: string | undefined | null): { appendSystemContext: string } | undefined => {
+          const finalBlock = staffPrefix + (block || "");
+          return finalBlock ? { appendSystemContext: finalBlock } : undefined;
+        };
+
+        // Dispatch-params path: workflow executor + task-dispatcher edge function
+        // can stash explicit `attached_sop_ids` / `attached_framework_ids` on the
+        // chat.send frame's metadata. When present, prefer them over the
+        // most-recent-conversation lookup and bypass cache (per-dispatch ids).
+        let dispatchIds = readDispatchAttachmentIds(ctx);
+        // Cycle 7b BUGSHOOT-1 (BUG 2) — DB-backed dispatch-context fallback for
+        // attachment ids. Same rationale as the subagent_id fallback above.
+        if (!dispatchIds.sopIds.length && !dispatchIds.fwIds.length && sessionKey) {
+          if (!dispatchCtxRow) {
+            dispatchCtxRow = await loadDispatchContextBySession(supabase, userId, sessionKey).catch(() => null);
+          }
+          if (dispatchCtxRow && (dispatchCtxRow.attached_sop_ids.length || dispatchCtxRow.attached_framework_ids.length)) {
+            dispatchIds = {
+              sopIds: dispatchCtxRow.attached_sop_ids,
+              fwIds: dispatchCtxRow.attached_framework_ids,
+            };
+            api.logger?.debug?.(
+              `[ofiere-attach] dispatch ids via dispatch_context (session=${sessionKey}) sops=${dispatchIds.sopIds.length} fws=${dispatchIds.fwIds.length}`,
+            );
+          }
+        }
+        if (dispatchIds.sopIds.length || dispatchIds.fwIds.length) {
+          api.logger?.debug?.(
+            `[ofiere-attach] dispatch ids agent=${resolvedAgentId} sops=${dispatchIds.sopIds.length} fws=${dispatchIds.fwIds.length}`,
+          );
+          const block = await renderBlockForIds({
+            supabase, userId,
+            sopIds: dispatchIds.sopIds,
+            fwIds: dispatchIds.fwIds,
+          });
+          return wrap(block);
+        }
+
+        // Staff-mode runs bypass the chief-level attachment cache so a chief
+        // and its staff never share a cached attachment block.
+        if (subagentId) {
+          const block = await buildAttachmentBlock({
+            supabase, userId, agentId: resolvedAgentId, subagentId,
+          });
+          return wrap(block);
+        }
+
+        // Multi-tenant: a single plugin process can serve multiple users — key
+        // by (userId, agentId) so User B never sees User A's cached block.
+        const cacheKey = `${userId}::${resolvedAgentId}`;
+        const cached = attachmentCache.get(cacheKey);
+        if (cached) {
+          const age = Date.now() - cached.at;
+          if (age < ATTACH_CACHE_TTL_MS) {
+            return wrap(cached.text);
+          }
+          if (age < ATTACH_CACHE_STALE_MS) {
+            // Refresh in background
+            (async () => {
+              try {
+                const fresh = await buildAttachmentBlock({ supabase, userId, agentId: resolvedAgentId });
+                attachmentCache.set(cacheKey, { text: fresh, at: Date.now() });
+              } catch { /* ignore */ }
+            })();
+            return wrap(cached.text);
+          }
+        }
+
+        const block = await buildAttachmentBlock({ supabase, userId, agentId: resolvedAgentId });
+        attachmentCache.set(cacheKey, { text: block, at: Date.now() });
+        return wrap(block);
+      } catch (e) {
+        api.logger?.debug?.(`[ofiere-attach] before_prompt_build error: ${e instanceof Error ? e.message : e}`);
+      }
+    });
+  } catch {
+    api.logger?.debug?.("[ofiere] Could not register attachment context hook — appendSystemContext may not be supported");
+  }
+}
+
+// Public for tests / future hooks that need to drop the cache
+export function invalidateAttachmentCache(): void {
+  attachmentCache.clear();
+}
+
+// Re-export tier invalidation so callers don't need to import two modules
+export { invalidateAgentTier };