ofiere-openclaw-plugin 4.37.2 → 4.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofiere-openclaw-plugin",
-  "version": "4.37.2",
+  "version": "4.38.0",
   "type": "module",
   "description": "OpenClaw plugin for Ofiere PM - 16 meta-tools covering tasks, agents, projects, scheduling, knowledge, workflows, notifications, memory, prompts, constellation, space file management, execution plan builder, SOP management, agent brain, talent management, and corporate frameworks",
   "keywords": ["openclaw", "ofiere", "project-management", "agents", "plugin"],

package/src/agent-tier.ts

@@ -0,0 +1,144 @@
+// src/agent-tier.ts — Plugin-side agent tier resolver.
+// Manual override (agent_tier_overrides) wins over auto-detection.
+// Mirrors dashboard/lib/agentTier.ts contracts so the dashboard UI
+// and plugin enforcement agree on every agent's tier.
+
+import type { SupabaseClient } from "@supabase/supabase-js";
+
+export type AgentTier = "c-suite" | "staff" | null;
+export type TierSource =
+  | "manual"
+  | "executiveRole"
+  | "roster"
+  | "subagent"
+  | "departmentRole"
+  | "none";
+
+export interface TierResolution {
+  tier: AgentTier;
+  source: TierSource;
+}
+
+// Hard-coded executive roster ids — match dashboard/lib/agentRoster.ts.
+// Anything in this set defaults to c-suite when no manual override exists.
+const ROSTER_IDS = new Set<string>([
+  "ofie",
+  "daisy",
+  "ivy",
+  "celia",
+  "thalia",
+  "sasha",
+  "agent-zero",
+]);
+
+interface CacheEntry { value: TierResolution; expires: number; }
+const TTL_MS = 5 * 60 * 1000;
+const cache = new Map<string, CacheEntry>();
+const k = (userId: string, agentId: string) => `${userId}::${agentId}`;
+
+export function invalidateAgentTier(userId: string, agentId?: string): void {
+  if (!agentId) {
+    for (const key of cache.keys()) if (key.startsWith(`${userId}::`)) cache.delete(key);
+    return;
+  }
+  cache.delete(k(userId, agentId));
+}
+
+export async function resolveAgentTier(
+  supabase: SupabaseClient,
+  agentId: string,
+  userId: string,
+): Promise<TierResolution> {
+  const id = (agentId || "").trim();
+  if (!id || !userId) return { tier: null, source: "none" };
+
+  const key = k(userId, id);
+  const hit = cache.get(key);
+  if (hit && hit.expires > Date.now()) return hit.value;
+
+  let result: TierResolution = { tier: null, source: "none" };
+
+  // 1. Manual override
+  try {
+    const { data } = await supabase
+      .from("agent_tier_overrides")
+      .select("tier")
+      .eq("user_id", userId)
+      .eq("agent_id", id)
+      .maybeSingle();
+    if (data?.tier === "c-suite" || data?.tier === "staff") {
+      result = { tier: data.tier, source: "manual" };
+      cache.set(key, { value: result, expires: Date.now() + TTL_MS });
+      return result;
+    }
+  } catch {
+    // Table missing in older installs — fall through
+  }
+
+  // 2. C-Suite: hardcoded roster
+  if (ROSTER_IDS.has(id)) {
+    result = { tier: "c-suite", source: "roster" };
+    cache.set(key, { value: result, expires: Date.now() + TTL_MS });
+    return result;
+  }
+
+  // 3. agent_architectures.executive_role / department_role
+  try {
+    const { data } = await supabase
+      .from("agent_architectures")
+      .select("executive_role, department_role")
+      .eq("user_id", userId)
+      .eq("agent_id", id)
+      .maybeSingle();
+    if (data?.department_role === "chief" ||
+        (data?.executive_role && String(data.executive_role).trim())) {
+      result = { tier: "c-suite", source: "executiveRole" };
+      cache.set(key, { value: result, expires: Date.now() + TTL_MS });
+      return result;
+    }
+    if (data?.department_role === "staff") {
+      result = { tier: "staff", source: "departmentRole" };
+      cache.set(key, { value: result, expires: Date.now() + TTL_MS });
+      return result;
+    }
+  } catch {
+    // Table missing — fall through
+  }
+
+  // 4. Staff: registered as subagent
+  try {
+    const { data } = await supabase
+      .from("agent_subagents")
+      .select("id")
+      .eq("user_id", userId)
+      .eq("id", id)
+      .maybeSingle();
+    if (data?.id) {
+      result = { tier: "staff", source: "subagent" };
+      cache.set(key, { value: result, expires: Date.now() + TTL_MS });
+      return result;
+    }
+  } catch {
+    // ignore
+  }
+
+  cache.set(key, { value: result, expires: Date.now() + TTL_MS });
+  return result;
+}
+
+export async function getAgentTier(
+  supabase: SupabaseClient,
+  agentId: string,
+  userId: string,
+): Promise<AgentTier> {
+  return (await resolveAgentTier(supabase, agentId, userId)).tier;
+}
+
+export function isDocKindValidForTier(
+  docKind: "sop" | "framework",
+  tier: AgentTier,
+): boolean {
+  if (tier === "c-suite") return docKind === "framework";
+  if (tier === "staff") return docKind === "sop";
+  return false;
+}

package/src/attach-token.ts

@@ -0,0 +1,106 @@
+// src/attach-token.ts — HMAC confirmation token for agent self-attach.
+// Mirrors dashboard/lib/attachmentToken.ts EXACTLY so tokens issued
+// here verify against the dashboard and vice-versa.
+//
+// Format: base64url(payload).base64url(sig)
+//   payload = JSON({ u, k, t, d, dk, exp })
+//   sig     = HMAC_SHA256(secret, payload)
+
+import { createHmac, timingSafeEqual } from "crypto";
+
+const TOKEN_TTL_MS = 5 * 60 * 1000;
+
+function getSecret(): string {
+  const s = process.env.OFIERE_ATTACH_SECRET;
+  if (!s) throw new Error("OFIERE_ATTACH_SECRET is not configured");
+  return s;
+}
+
+function b64urlEncode(buf: Buffer | string): string {
+  const b = typeof buf === "string" ? Buffer.from(buf, "utf8") : buf;
+  return b.toString("base64").replace(/=+$/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+
+function b64urlDecode(s: string): Buffer {
+  const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - (s.length % 4));
+  return Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/") + pad, "base64");
+}
+
+interface TokenPayload {
+  u: string;
+  k: string;
+  t: string;
+  d: string[];
+  dk: "sop" | "framework";
+  exp: number;
+}
+
+export interface IssueArgs {
+  userId: string;
+  targetKind: string;
+  targetId: string;
+  docKind: "sop" | "framework";
+  docIds: string[];
+  ttlMs?: number;
+}
+
+export function issueAttachmentToken(args: IssueArgs): string {
+  const exp = Date.now() + (args.ttlMs ?? TOKEN_TTL_MS);
+  const payload: TokenPayload = {
+    u: args.userId,
+    k: args.targetKind,
+    t: args.targetId,
+    d: [...args.docIds].sort(),
+    dk: args.docKind,
+    exp,
+  };
+  const json = JSON.stringify(payload);
+  const sig = createHmac("sha256", getSecret()).update(json).digest();
+  return `${b64urlEncode(json)}.${b64urlEncode(sig)}`;
+}
+
+export interface VerifyArgs {
+  token: string;
+  userId: string;
+  targetKind: string;
+  targetId: string;
+  docKind: "sop" | "framework";
+  docIds: string[];
+}
+
+export type VerifyResult =
+  | { ok: true }
+  | { ok: false; reason: "malformed" | "bad_signature" | "expired" | "mismatch" };
+
+export function verifyAttachmentToken(args: VerifyArgs): VerifyResult {
+  const parts = args.token.split(".");
+  if (parts.length !== 2) return { ok: false, reason: "malformed" };
+  let payload: TokenPayload;
+  try {
+    payload = JSON.parse(b64urlDecode(parts[0]).toString("utf8"));
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+
+  const expectedJson = JSON.stringify(payload);
+  const expectedSig = createHmac("sha256", getSecret()).update(expectedJson).digest();
+  const providedSig = b64urlDecode(parts[1]);
+  if (expectedSig.length !== providedSig.length) return { ok: false, reason: "bad_signature" };
+  if (!timingSafeEqual(expectedSig, providedSig)) return { ok: false, reason: "bad_signature" };
+
+  if (typeof payload.exp !== "number" || payload.exp < Date.now()) {
+    return { ok: false, reason: "expired" };
+  }
+  if (payload.u !== args.userId) return { ok: false, reason: "mismatch" };
+  if (payload.k !== args.targetKind || payload.t !== args.targetId) return { ok: false, reason: "mismatch" };
+  if (payload.dk !== args.docKind) return { ok: false, reason: "mismatch" };
+
+  const sortedRequested = [...args.docIds].sort();
+  if (
+    payload.d.length !== sortedRequested.length ||
+    payload.d.some((v, i) => v !== sortedRequested[i])
+  ) {
+    return { ok: false, reason: "mismatch" };
+  }
+  return { ok: true };
+}

package/src/attachments.ts

@@ -0,0 +1,391 @@
+// 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 {
+  resolveAgentTier,
+  isDocKindValidForTier,
+  invalidateAgentTier,
+} from "./agent-tier.js";
+import { issueAttachmentToken, verifyAttachmentToken } from "./attach-token.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";
+export type DocKind = "sop" | "framework";
+
+const VALID_TARGETS: ReadonlyArray<TargetKind> = ["conversation", "task", "scheduler_event"];
+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 };
+  }
+
+  return { ok: false, error: "unsupported target_kind" };
+}
+
+// ── Load target row (mainly to read its agent_id for tier check) ──
+async function loadTargetAgentId(args: {
+  supabase: SupabaseClient;
+  userId: string;
+  targetKind: TargetKind;
+  targetId: string;
+}): Promise<string | null> {
+  const { supabase, userId, targetKind, targetId } = args;
+  const tbl =
+    targetKind === "conversation" ? "conversations" :
+    targetKind === "task" ? "tasks" : "scheduler_events";
+  const { data } = await supabase
+    .from(tbl)
+    .select("agent_id")
+    .eq("user_id", userId)
+    .eq("id", targetId)
+    .maybeSingle();
+  return (data?.agent_id as string) || 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 targetAgentId = await loadTargetAgentId({
+    supabase, userId, targetKind, targetId,
+  });
+  if (!targetAgentId) return err("target_not_found_or_no_agent");
+
+  const tierResolution = await resolveAgentTier(supabase, targetAgentId, 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");
+}
+
+async function buildAttachmentBlock(args: {
+  supabase: SupabaseClient;
+  userId: string;
+  agentId: string;
+}): Promise<string> {
+  const { supabase, userId, agentId } = args;
+
+  // 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) || [];
+  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 });
+}
+
+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;
+
+        const cacheKey = resolvedAgentId;
+        const cached = attachmentCache.get(cacheKey);
+        if (cached) {
+          const age = Date.now() - cached.at;
+          if (age < ATTACH_CACHE_TTL_MS) {
+            return cached.text ? { appendSystemContext: cached.text } : undefined;
+          }
+          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 cached.text ? { appendSystemContext: cached.text } : undefined;
+          }
+        }
+
+        const block = await buildAttachmentBlock({ supabase, userId, agentId: resolvedAgentId });
+        attachmentCache.set(cacheKey, { text: block, at: Date.now() });
+        return block ? { appendSystemContext: block } : undefined;
+      } 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 };

package/src/prompt.ts

@@ -24,9 +24,10 @@ const TOOL_SUMMARIES: Record<string, string> = {
   OFIERE_CONSTELLATION_OPS: "Create/edit/delete OpenClaw agents from chat",
   OFIERE_FILE_OPS: "Space files: upload, read, move, share, delete",
   OFIERE_PLAN_OPS: "Visual execution plan builder (DAG drafts → real tasks)",
-  OFIERE_SOP_OPS: "Standard Operating Procedures for department chiefs",
+  OFIERE_SOP_OPS: "Standard Operating Procedures (Staff agents). Includes propose_attach/commit_attach for self-attaching SOPs to runs",
   OFIERE_BRAIN_OPS: "Agent memory, knowledge graph, self-improvement (TMT/MAGMA)",
   OFIERE_TALENT_OPS: "Talents: list, get, activate, deactivate cognitive skill presets",
+  OFIERE_FRAMEWORK_OPS: "Corporate Frameworks (C-Suite agents). Includes propose_attach/commit_attach for self-attaching Frameworks to runs",
 };
 
 // ─── Tier B: Full Tool Documentation ────────────────────────────────────────
@@ -105,10 +106,11 @@ Actions: "list", "get", "create", "update", "delete", "add_nodes", "execute"
 - Node types: task, gate, milestone
 - Execution maps ALL fields: execution_steps, goals, constraints, system_prompt`,
 
-  OFIERE_SOP_OPS: `Standard Operating Procedures for department chiefs.
-Actions: "list_templates", "create", "list", "get", "update", "delete", "list_subagents", "apply_template"
+  OFIERE_SOP_OPS: `Standard Operating Procedures.
+Actions: "list_templates", "create", "list", "get", "update", "delete", "list_subagents", "apply_template", "propose_attach", "commit_attach"
 - sop_data: { title, purpose, scope, applicability, prerequisites:{ conditions, required_tools, required_permissions, safety_warnings }, procedure_steps[], expected_outputs[], escalation_rules[], acceptance_criteria[], rollback_procedure, notes }
 - Legacy field names still accepted (objective→purpose, steps→procedure_steps, deliverables→expected_outputs, escalationRules→escalation_rules, successCriteria→acceptance_criteria) — prefer new names.
+- propose_attach / commit_attach: attach SOPs to a run (target_kind: conversation|task|scheduler_event). Tier rule: SOPs only attach to STAFF-tier targets; for c-suite use OFIERE_FRAMEWORK_OPS instead. propose_attach returns a token-cost summary + confirmation_token (5-min ttl). You MUST surface the cost and ask the user before calling commit_attach. The user must explicitly approve.
 - See SOP PROTOCOL section for when to load vs skip`,
 
   OFIERE_BRAIN_OPS: `Agent memory, knowledge graph, self-improvement (TMT/MAGMA).
@@ -124,6 +126,11 @@ Actions: "list", "get", "activate", "deactivate"
 - deactivate: Disable a talent (status → inactive). Required: talent_id
 - Active talents inject their execution_protocol and guardrails into your system prompt automatically
 - Talents chain other tools: SPHINX chains KNOWLEDGE_OPS+BRAIN_OPS, PRISM chains BRAIN_OPS trajectories, ATLAS chains PLAN_OPS+TASK_OPS+SOP_OPS`,
+
+  OFIERE_FRAMEWORK_OPS: `Corporate Frameworks — strategic mandates, KPIs, risk governance.
+Actions: "create", "list", "get", "update", "delete", "propose_attach", "commit_attach"
+- content: JSON string with { mission, vision, core_principles[], decision_authority, budget_constraints, resource_limits, tool_stack[], strategic_objectives[], risk_appetite, compliance_requirements[], escalation_matrix[], team_composition (STRING — paragraph or newline-joined, NOT an array), integration_points[], review_frequency, last_reviewed, next_review, notes }
+- propose_attach / commit_attach: attach Frameworks to a run (target_kind: conversation|task|scheduler_event). Tier rule: Frameworks only attach to C-SUITE-tier targets; for staff use OFIERE_SOP_OPS instead. propose_attach returns a token-cost summary + confirmation_token (5-min ttl). You MUST surface the cost and ask the user before calling commit_attach. The user must explicitly approve.`,
 };
 
 export function getSystemPrompt(state: {

package/src/sop-render.ts

@@ -0,0 +1,216 @@
+// src/sop-render.ts — Plugin-side markdown renderer for SOPs and Frameworks.
+// Mirrors dashboard/lib/sopRender.ts. Output is what gets prepended/appended to
+// the system prompt during `before_prompt_build`.
+
+interface SOPCheckItem { text?: string; checked?: boolean; }
+interface SOPStep {
+  name?: string; action?: string; owner?: string; output?: string;
+  decision_logic?: string; failure_state?: string; fallback_action?: string;
+  estimated_duration?: string;
+}
+interface SOPEscalationRule { trigger?: string; escalateTo?: string; priority?: string; }
+interface SOPPrerequisites {
+  conditions?: SOPCheckItem[]; required_tools?: string[];
+  required_permissions?: string[]; safety_warnings?: string[];
+}
+export interface SOPData {
+  title?: string;
+  purpose?: string; scope?: string; applicability?: string;
+  prerequisites?: SOPPrerequisites;
+  procedure_steps?: SOPStep[];
+  expected_outputs?: string[];
+  acceptance_criteria?: SOPCheckItem[];
+  escalation_rules?: SOPEscalationRule[];
+  rollback_procedure?: string;
+  notes?: string;
+}
+
+interface FrameworkObjective {
+  objective?: string; target?: string; measurement?: string; frequency?: string;
+}
+interface FrameworkEscalation {
+  trigger?: string; escalate_to?: string; priority?: string; response_sla?: string;
+}
+export interface FrameworkData {
+  title?: string;
+  mission?: string; vision?: string;
+  core_principles?: string[];
+  decision_authority?: string; budget_constraints?: string;
+  resource_limits?: string; tool_stack?: string[];
+  strategic_objectives?: FrameworkObjective[];
+  risk_appetite?: string; compliance_requirements?: string[];
+  escalation_matrix?: FrameworkEscalation[];
+  team_composition?: string; integration_points?: string[];
+  review_frequency?: string; last_reviewed?: string; next_review?: string;
+  notes?: string;
+}
+
+function bullet(items: (string | undefined | null)[]): string {
+  const cleaned = items.map((s) => (s ?? "").toString().trim()).filter(Boolean);
+  return cleaned.length ? cleaned.map((s) => `- ${s}`).join("\n") : "";
+}
+
+function section(label: string, body: string): string {
+  const trimmed = body.trim();
+  return trimmed ? `### ${label}\n${trimmed}` : "";
+}
+
+function joinSections(parts: string[]): string {
+  return parts.filter(Boolean).join("\n\n");
+}
+
+function safeParse<T = unknown>(s: string): T | null {
+  try { return JSON.parse(s) as T; } catch { return null; }
+}
+
+export function renderSopMarkdown(input: string | SOPData | null | undefined): string {
+  if (input == null) return "";
+  const data: SOPData = typeof input === "string"
+    ? (safeParse<SOPData>(input) || {})
+    : input;
+
+  const parts: string[] = [];
+  if (data.purpose) parts.push(section("Purpose", data.purpose));
+  if (data.scope) parts.push(section("Scope", data.scope));
+  if (data.applicability) parts.push(section("Applicability", data.applicability));
+
+  const prereq = data.prerequisites;
+  if (prereq) {
+    const pieces: string[] = [];
+    const cond = (prereq.conditions || []).map((c) => c?.text).filter(Boolean) as string[];
+    if (cond.length) pieces.push(`**Conditions:**\n${bullet(cond)}`);
+    if (prereq.required_tools?.length) pieces.push(`**Required tools:**\n${bullet(prereq.required_tools)}`);
+    if (prereq.required_permissions?.length) pieces.push(`**Required permissions:**\n${bullet(prereq.required_permissions)}`);
+    if (prereq.safety_warnings?.length) pieces.push(`**Safety warnings:**\n${bullet(prereq.safety_warnings)}`);
+    if (pieces.length) parts.push(section("Prerequisites", pieces.join("\n\n")));
+  }
+
+  if (data.procedure_steps?.length) {
+    const steps = data.procedure_steps.map((step, i) => {
+      const lines: string[] = [`${i + 1}. **${step.name || `Step ${i + 1}`}**`];
+      if (step.action) lines.push(`   - Action: ${step.action}`);
+      if (step.owner) lines.push(`   - Owner: ${step.owner}`);
+      if (step.output) lines.push(`   - Output: ${step.output}`);
+      if (step.decision_logic) lines.push(`   - Decision logic: ${step.decision_logic}`);
+      if (step.failure_state) lines.push(`   - Failure state: ${step.failure_state}`);
+      if (step.fallback_action) lines.push(`   - Fallback: ${step.fallback_action}`);
+      if (step.estimated_duration) lines.push(`   - ETA: ${step.estimated_duration}`);
+      return lines.join("\n");
+    }).join("\n");
+    parts.push(section("Procedure", steps));
+  }
+
+  if (data.expected_outputs?.length) parts.push(section("Expected Outputs", bullet(data.expected_outputs)));
+  if (data.acceptance_criteria?.length) {
+    parts.push(section("Acceptance Criteria", bullet(data.acceptance_criteria.map((c) => c?.text || ""))));
+  }
+
+  if (data.escalation_rules?.length) {
+    const rules = data.escalation_rules
+      .filter((r) => r.trigger || r.escalateTo)
+      .map((r) => `- [${r.priority || "P2"}] ${r.trigger || "(unspecified trigger)"} → ${r.escalateTo || "(unspecified)"}`)
+      .join("\n");
+    if (rules) parts.push(section("Escalation", rules));
+  }
+
+  if (data.rollback_procedure) parts.push(section("Rollback", data.rollback_procedure));
+  if (data.notes) parts.push(section("Notes", data.notes));
+
+  return joinSections(parts);
+}
+
+export function renderFrameworkMarkdown(input: string | FrameworkData | null | undefined): string {
+  if (input == null) return "";
+  const data: FrameworkData = typeof input === "string"
+    ? (safeParse<FrameworkData>(input) || {})
+    : input;
+
+  const parts: string[] = [];
+  if (data.mission) parts.push(section("Mission", data.mission));
+  if (data.vision) parts.push(section("Vision", data.vision));
+  if (data.core_principles?.length) parts.push(section("Core Principles", bullet(data.core_principles)));
+
+  const authParts: string[] = [];
+  if (data.decision_authority) authParts.push(`**Decision authority:** ${data.decision_authority}`);
+  if (data.budget_constraints) authParts.push(`**Budget constraints:** ${data.budget_constraints}`);
+  if (data.resource_limits) authParts.push(`**Resource limits:** ${data.resource_limits}`);
+  if (data.tool_stack?.length) authParts.push(`**Tool stack:**\n${bullet(data.tool_stack)}`);
+  if (authParts.length) parts.push(section("Authority & Constraints", authParts.join("\n\n")));
+
+  if (data.strategic_objectives?.length) {
+    const rows = data.strategic_objectives
+      .filter((o) => o.objective || o.target)
+      .map((o) => {
+        const bits = [
+          o.objective ? `**${o.objective}**` : "",
+          o.target ? `target: ${o.target}` : "",
+          o.measurement ? `measure: ${o.measurement}` : "",
+          o.frequency ? `cadence: ${o.frequency}` : "",
+        ].filter(Boolean);
+        return `- ${bits.join(" · ")}`;
+      })
+      .join("\n");
+    if (rows) parts.push(section("Strategic Objectives (KPIs)", rows));
+  }
+
+  const riskParts: string[] = [];
+  if (data.risk_appetite) riskParts.push(`**Risk appetite:** ${data.risk_appetite}`);
+  if (data.compliance_requirements?.length) riskParts.push(`**Compliance:**\n${bullet(data.compliance_requirements)}`);
+  if (riskParts.length) parts.push(section("Risk & Compliance", riskParts.join("\n\n")));
+
+  if (data.escalation_matrix?.length) {
+    const rows = data.escalation_matrix
+      .filter((e) => e.trigger || e.escalate_to)
+      .map((e) => {
+        const sla = e.response_sla ? ` (SLA ${e.response_sla})` : "";
+        return `- [${e.priority || "P2"}] ${e.trigger || "(unspecified)"} → ${e.escalate_to || "(unspecified)"}${sla}`;
+      })
+      .join("\n");
+    if (rows) parts.push(section("Escalation Matrix", rows));
+  }
+
+  const teamParts: string[] = [];
+  if (data.team_composition) teamParts.push(`**Team:** ${data.team_composition}`);
+  if (data.integration_points?.length) teamParts.push(`**Integration points:**\n${bullet(data.integration_points)}`);
+  if (teamParts.length) parts.push(section("Team & Integrations", teamParts.join("\n\n")));
+
+  if (data.review_frequency || data.next_review) {
+    const lines = [
+      data.review_frequency ? `**Review cadence:** ${data.review_frequency}` : "",
+      data.last_reviewed ? `**Last reviewed:** ${data.last_reviewed}` : "",
+      data.next_review ? `**Next review:** ${data.next_review}` : "",
+    ].filter(Boolean);
+    if (lines.length) parts.push(section("Review Cycle", lines.join("\n")));
+  }
+
+  if (data.notes) parts.push(section("Notes", data.notes));
+
+  return joinSections(parts);
+}
+
+export function renderAttachmentBlock(args: {
+  sops?: Array<{ title: string; content: string }>;
+  frameworks?: Array<{ title: string; content: string }>;
+}): string {
+  const blocks: string[] = [];
+
+  if (args.frameworks?.length) {
+    const sections = args.frameworks.map((fw) => {
+      const md = renderFrameworkMarkdown(fw.content);
+      if (!md) return `## ${fw.title}\n_(empty)_`;
+      return `## ${fw.title}\n${md}`;
+    }).join("\n\n");
+    blocks.push(`[FRAMEWORKS — ATTACHED]\nThese frameworks are active for this run. Orient strategic decisions toward them.\n\n${sections}`);
+  }
+
+  if (args.sops?.length) {
+    const sections = args.sops.map((sop) => {
+      const md = renderSopMarkdown(sop.content);
+      if (!md) return `## ${sop.title}\n_(empty)_`;
+      return `## ${sop.title}\n${md}`;
+    }).join("\n\n");
+    blocks.push(`[SOPS — ATTACHED]\nThese SOPs are active for this run. Follow the procedure steps and escalation rules.\n\n${sections}`);
+  }
+
+  return blocks.join("\n\n");
+}

package/src/tools.ts

@@ -13,6 +13,11 @@
 import type { SupabaseClient } from "@supabase/supabase-js";
 import type { OfiereConfig } from "./types.js";
 import { resolveAgentId } from "./agent-resolver.js";
+import {
+  handleProposeAttach,
+  handleCommitAttach,
+  registerAttachmentContextHook,
+} from "./attachments.js";
 
 // ─── Tool result shape (matches OpenClaw SDK) ────────────────────────────────
 
@@ -4843,7 +4848,10 @@ function registerSOPOps(
       `- "update": Modify SOP. Required: sop_id. Optional: title, sop_data, status, department\n` +
       `- "delete": Remove SOP. Required: sop_id\n` +
       `- "list_subagents": List subagents for a chief. Required: chief_agent_id\n` +
-      `- "apply_template": Create SOP from template. Required: agent_id, template_id. Optional: title, department\n\n` +
+      `- "apply_template": Create SOP from template. Required: agent_id, template_id. Optional: title, department\n` +
+      `- "propose_attach": Propose attaching SOPs to a run target (conversation/task/scheduler_event). Returns token cost + confirmation_token. Required: target_kind, target_id, doc_ids[]. The user MUST be asked to approve before commit.\n` +
+      `- "commit_attach": Commit a proposed attachment. Required: target_kind, target_id, doc_ids[], confirmation_token (from propose_attach). Only call AFTER user approves the token cost.\n` +
+      `Tier rule: SOPs only attach to targets whose assigned agent is Staff. Use OFIERE_FRAMEWORK_OPS for c-suite targets.\n\n` +
       `sop_data structure (JSON object):\n` +
       `{\n` +
       `  title: string,\n` +
@@ -4863,11 +4871,15 @@ function registerSOPOps(
       type: "object",
       required: ["action"],
       properties: {
-        action: { type: "string", enum: ["list_templates", "create", "list", "get", "update", "delete", "list_subagents", "apply_template"], description: "Valid actions: list_templates, create, list, get, update, delete, list_subagents, apply_template" },
+        action: { type: "string", enum: ["list_templates", "create", "list", "get", "update", "delete", "list_subagents", "apply_template", "propose_attach", "commit_attach"], description: "Valid actions: list_templates, create, list, get, update, delete, list_subagents, apply_template, propose_attach, commit_attach" },
         sop_id: { type: "string", description: "SOP ID (required for get, update, delete)" },
         agent_id: { type: "string", description: "Agent ID (required for create, list filter, apply_template)" },
         chief_agent_id: { type: "string", description: "Chief agent ID (required for list_subagents)" },
         template_id: { type: "string", description: "Template ID (required for apply_template)" },
+        target_kind: { type: "string", enum: ["conversation", "task", "scheduler_event"], description: "Run target kind (for propose_attach/commit_attach)" },
+        target_id: { type: "string", description: "Run target id (for propose_attach/commit_attach)" },
+        doc_ids: { type: "array", items: { type: "string" }, description: "SOP ids to attach (for propose_attach/commit_attach)" },
+        confirmation_token: { type: "string", description: "Token returned by propose_attach. Required for commit_attach." },
         title: { type: "string", description: "SOP title" },
         department: { type: "string", description: "Department name (e.g. Marketing & Revenue)" },
         status: { type: "string", enum: ["draft", "active", "archived", "under_review"], description: "SOP status" },
@@ -4921,7 +4933,9 @@ function registerSOPOps(
         case "delete": return handleSOPDelete(supabase, userId, params);
         case "list_subagents": return handleSOPListSubagents(supabase, userId, params);
         case "apply_template": return handleSOPApplyTemplate(supabase, userId, resolveAgent, params);
-        default: return err(`Unknown action "${action}". Valid: list_templates, create, list, get, update, delete, list_subagents, apply_template`);
+        case "propose_attach": return handleProposeAttach({ supabase, userId, docKind: "sop", params });
+        case "commit_attach": return handleCommitAttach({ supabase, userId, docKind: "sop", params });
+        default: return err(`Unknown action "${action}". Valid: list_templates, create, list, get, update, delete, list_subagents, apply_template, propose_attach, commit_attach`);
       }
     },
   });
@@ -5237,7 +5251,10 @@ function registerFrameworkOps(
       `- "list": List frameworks. Optional: agent_id to filter\n` +
       `- "get": Get full framework details. Required: framework_id\n` +
       `- "update": Modify framework. Required: framework_id. Optional: title, content, status, department, category\n` +
-      `- "delete": Remove framework. Required: framework_id\n\n` +
+      `- "delete": Remove framework. Required: framework_id\n` +
+      `- "propose_attach": Propose attaching Frameworks to a run target. Returns token cost + confirmation_token. Required: target_kind, target_id, doc_ids[]. The user MUST be asked to approve before commit.\n` +
+      `- "commit_attach": Commit a proposed attachment. Required: target_kind, target_id, doc_ids[], confirmation_token (from propose_attach). Only call AFTER user approves the token cost.\n` +
+      `Tier rule: Frameworks only attach to targets whose assigned agent is C-Suite. Use OFIERE_SOP_OPS for staff targets.\n\n` +
       `content: A JSON string containing the full framework body. Example:\n` +
       `"{\\"mission\\":\\"Drive brand growth\\",\\"vision\\":\\"Market leader by 2027\\",\\"core_principles\\":[\\"Data-driven\\",\\"Customer-first\\"],` +
       `\\"decision_authority\\":\\"CMO approves >$10k spend\\",\\"budget_constraints\\":\\"$50k monthly cap\\",` +
@@ -5254,7 +5271,7 @@ function registerFrameworkOps(
       type: "object",
       required: ["action"],
       properties: {
-        action: { type: "string", enum: ["create", "list", "get", "update", "delete"], description: "Framework action" },
+        action: { type: "string", enum: ["create", "list", "get", "update", "delete", "propose_attach", "commit_attach"], description: "Framework action" },
         framework_id: { type: "string", description: "Framework ID (required for get, update, delete)" },
         agent_id: { type: "string", description: "Agent ID (required for create, optional filter for list)" },
         title: { type: "string", description: "Framework title" },
@@ -5262,6 +5279,10 @@ function registerFrameworkOps(
         department: { type: "string" },
         category: { type: "string" },
         status: { type: "string", enum: ["draft", "active", "under_review", "archived"] },
+        target_kind: { type: "string", enum: ["conversation", "task", "scheduler_event"], description: "Run target kind (for propose_attach/commit_attach)" },
+        target_id: { type: "string", description: "Run target id (for propose_attach/commit_attach)" },
+        doc_ids: { type: "array", items: { type: "string" }, description: "Framework ids to attach (for propose_attach/commit_attach)" },
+        confirmation_token: { type: "string", description: "Token returned by propose_attach. Required for commit_attach." },
       },
     },
     async execute(_id: string, params: Record<string, unknown>) {
@@ -5272,7 +5293,9 @@ function registerFrameworkOps(
         case "get": return handleFWGet(supabase, userId, params);
         case "update": return handleFWUpdate(supabase, userId, params);
         case "delete": return handleFWDelete(supabase, userId, params);
-        default: return err(`Unknown action "${action}". Valid: create, list, get, update, delete`);
+        case "propose_attach": return handleProposeAttach({ supabase, userId, docKind: "framework", params });
+        case "commit_attach": return handleCommitAttach({ supabase, userId, docKind: "framework", params });
+        default: return err(`Unknown action "${action}". Valid: create, list, get, update, delete, propose_attach, commit_attach`);
       }
     },
   });
@@ -6127,6 +6150,9 @@ export function registerTools(
   // ── Register talent context hook ──
   registerTalentContextHook(api, supabase, userId, fallbackAgentId);
 
+  // ── Register attachment context hook (SOPs/Frameworks injection) ──
+  registerAttachmentContextHook({ api, supabase, userId, fallbackAgentId, resolveAgent });
+
   // ── Register agent_end hook for server-side brain extraction ──
   registerBrainExtractionHook(api, supabase, userId, fallbackAgentId);