@byte5ai/palaia 2.1.0 → 2.2.0

package/src/hooks/state.ts

@@ -0,0 +1,317 @@
+/**
+ * Session-isolated turn state, plugin state persistence, and session key helpers.
+ *
+ * Extracted from hooks.ts during Phase 1.5 decomposition.
+ * No logic changes — pure structural refactoring.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { PalaiaPluginConfig } from "../config.js";
+
+// ============================================================================
+// Plugin State Persistence (Issue #87: Recall counter for nudges)
+// ============================================================================
+
+export interface PluginState {
+  successfulRecalls: number;
+  satisfactionNudged: boolean;
+  transparencyNudged: boolean;
+  firstRecallTimestamp: string | null;
+}
+
+export const DEFAULT_PLUGIN_STATE: PluginState = {
+  successfulRecalls: 0,
+  satisfactionNudged: false,
+  transparencyNudged: false,
+  firstRecallTimestamp: null,
+};
+
+/**
+ * Load plugin state from disk.
+ *
+ * Note: No file locking is applied here. The plugin-state.json file stores
+ * non-critical counters (recall count, nudge flags). In the worst case of a
+ * race condition between multiple agents, a nudge fires one recall too early
+ * or too late. This is acceptable given the low-stakes nature of the data
+ * and the complexity cost of adding advisory locks in Node.js.
+ */
+export async function loadPluginState(workspace?: string): Promise<PluginState> {
+  const dir = workspace || process.cwd();
+  const statePath = path.join(dir, ".palaia", "plugin-state.json");
+  try {
+    const raw = await fs.readFile(statePath, "utf-8");
+    return { ...DEFAULT_PLUGIN_STATE, ...JSON.parse(raw) };
+  } catch {
+    return { ...DEFAULT_PLUGIN_STATE };
+  }
+}
+
+export async function savePluginState(state: PluginState, workspace?: string): Promise<void> {
+  const dir = workspace || process.cwd();
+  const statePath = path.join(dir, ".palaia", "plugin-state.json");
+  try {
+    await fs.writeFile(statePath, JSON.stringify(state, null, 2));
+  } catch {
+    // Non-fatal
+  }
+}
+
+// ============================================================================
+// Session-isolated Turn State (Issue #87: Emoji Reactions)
+// ============================================================================
+
+/** Per-session turn state for tracking recall/capture across hooks. */
+export interface TurnState {
+  recallOccurred: boolean;
+  lastInboundMessageId: string | null;
+  lastInboundChannelId: string | null;
+  channelProvider: string | null;
+  capturedInThisTurn: boolean;
+  /** Timestamp when this entry was created (for TTL-based pruning). */
+  createdAt: number;
+}
+
+function createDefaultTurnState(): TurnState {
+  return {
+    recallOccurred: false,
+    lastInboundMessageId: null,
+    lastInboundChannelId: null,
+    channelProvider: null,
+    capturedInThisTurn: false,
+    createdAt: Date.now(),
+  };
+}
+
+/** Maximum age for turn state entries before they are pruned (5 minutes). */
+const TURN_STATE_TTL_MS = 5 * 60 * 1000;
+/** Maximum age for inbound message entries before they are pruned (5 minutes). */
+const INBOUND_MESSAGE_TTL_MS = 5 * 60 * 1000;
+
+/**
+ * Session-isolated turn state map. Keyed by sessionKey.
+ * Set in before_prompt_build / message_received, consumed + deleted in agent_end.
+ * NEVER use global variables for turn data — race condition with multi-agent.
+ */
+export const turnStateBySession = new Map<string, TurnState>();
+
+// ============================================================================
+// Inbound Message ID Store (for emoji reactions)
+// ============================================================================
+
+/**
+ * Stores the most recent inbound message ID per channel.
+ * Keyed by channelId (e.g. "C0AKE2G15HV"), value is the message ts.
+ * Written by message_received, consumed by agent_end.
+ * Entries are short-lived and cleaned up after agent_end.
+ */
+export const lastInboundMessageByChannel = new Map<string, { messageId: string; provider: string; timestamp: number }>();
+
+/** Channels that support emoji reactions. */
+export const REACTION_SUPPORTED_PROVIDERS = new Set(["slack", "discord"]);
+
+/**
+ * Remove stale entries from turnStateBySession and lastInboundMessageByChannel.
+ * Called at the start of before_prompt_build to prevent memory leaks from
+ * sessions that were killed/crashed without firing agent_end.
+ */
+export function pruneStaleEntries(): void {
+  const now = Date.now();
+  for (const [key, state] of turnStateBySession) {
+    if (now - state.createdAt > TURN_STATE_TTL_MS) {
+      turnStateBySession.delete(key);
+    }
+  }
+  for (const [key, entry] of lastInboundMessageByChannel) {
+    if (now - entry.timestamp > INBOUND_MESSAGE_TTL_MS) {
+      lastInboundMessageByChannel.delete(key);
+    }
+  }
+}
+
+/**
+ * Get or create turn state for a session.
+ */
+export function getOrCreateTurnState(sessionKey: string): TurnState {
+  let state = turnStateBySession.get(sessionKey);
+  if (!state) {
+    state = createDefaultTurnState();
+    turnStateBySession.set(sessionKey, state);
+  }
+  return state;
+}
+
+/**
+ * Delete turn state for a session (cleanup after agent_end).
+ */
+export function deleteTurnState(sessionKey: string): void {
+  turnStateBySession.delete(sessionKey);
+}
+
+/** Reset all turn state, inbound message store (for testing and cleanup). */
+export function resetTurnState(): void {
+  turnStateBySession.clear();
+  lastInboundMessageByChannel.clear();
+}
+
+// ============================================================================
+// Session Key Helpers
+// ============================================================================
+
+/**
+ * Extract channel target from a session key.
+ * e.g. "agent:main:slack:channel:c0ake2g15hv" -> "channel:C0AKE2G15HV"
+ */
+export function extractTargetFromSessionKey(sessionKey: string): string | undefined {
+  const parts = sessionKey.split(":");
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (parts[i] === "channel" || parts[i] === "dm" || parts[i] === "group") {
+      return `${parts[i]}:${parts[i + 1].toUpperCase()}`;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Extract channel provider from a session key.
+ * e.g. "agent:main:slack:channel:c0ake2g15hv" -> "slack"
+ */
+export function extractChannelFromSessionKey(sessionKey: string): string | undefined {
+  const parts = sessionKey.split(":");
+  if (parts.length >= 5 && parts[0] === "agent") {
+    return parts[2];
+  }
+  return undefined;
+}
+
+/**
+ * Extract the Slack channel ID from a session key.
+ * e.g. "agent:main:slack:channel:c0ake2g15hv" -> "C0AKE2G15HV"
+ */
+export function extractSlackChannelIdFromSessionKey(sessionKey: string): string | undefined {
+  const parts = sessionKey.split(":");
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (parts[i] === "channel" || parts[i] === "dm") {
+      return parts[i + 1].toUpperCase();
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Extract the real Slack channel ID from event metadata or ctx.
+ * OpenClaw stores the channel in "channel:C0AKE2G15HV" format in:
+ *   - event.metadata.to
+ *   - event.metadata.originatingTo
+ *   - ctx.conversationId
+ *
+ * ctx.channelId is the PROVIDER NAME ("slack"), not the channel ID.
+ * ctx.sessionKey is null during message_received.
+ */
+export function extractChannelIdFromEvent(event: any, ctx: any): string | undefined {
+  const rawTo = event?.metadata?.to
+    ?? event?.metadata?.originatingTo
+    ?? ctx?.conversationId
+    ?? "";
+  const match = String(rawTo).match(/^(?:channel|dm|group):([A-Z0-9]+)$/i);
+  return match ? match[1].toUpperCase() : undefined;
+}
+
+/**
+ * Resolve the session key for the current turn from available ctx.
+ * Tries ctx.sessionKey first, then falls back to sessionId.
+ */
+export function resolveSessionKeyFromCtx(ctx: any): string | undefined {
+  const sk = ctx?.sessionKey?.trim?.();
+  if (sk) return sk;
+  const sid = ctx?.sessionId?.trim?.();
+  return sid || undefined;
+}
+
+// ============================================================================
+// Scope Validation (Issue #90)
+// ============================================================================
+
+const VALID_SCOPES = ["private", "team", "public"];
+
+/**
+ * Check if a scope string is valid for palaia write.
+ * Valid: "private", "team", "public", or any "shared:*" prefix.
+ */
+export function isValidScope(s: string): boolean {
+  return VALID_SCOPES.includes(s) || s.startsWith("shared:");
+}
+
+/**
+ * Sanitize a scope value -- returns the value if valid, otherwise fallback.
+ * Enforces: LLM may suggest private or team, but NEVER public (unless explicitly configured).
+ */
+export function sanitizeScope(rawScope: string | null | undefined, fallback = "team", allowPublic = false): string {
+  if (!rawScope || !isValidScope(rawScope)) return fallback;
+  // Block public scope unless explicitly allowed (config-level override)
+  if (rawScope === "public" && !allowPublic) return fallback;
+  return rawScope;
+}
+
+// ============================================================================
+// Hook helpers
+// ============================================================================
+
+/**
+ * Resolve per-agent workspace and agentId from hook context.
+ * Fallback chain: ctx.workspaceDir -> config.workspace -> cwd
+ * Agent chain: ctx.agentId -> PALAIA_AGENT env var -> undefined
+ */
+export function resolvePerAgentContext(ctx: any, config: PalaiaPluginConfig) {
+  return {
+    workspace: ctx?.workspaceDir || config.workspace,
+    agentId: ctx?.agentId || process.env.PALAIA_AGENT || undefined,
+  };
+}
+
+// ============================================================================
+// /palaia status command -- Format helpers
+// ============================================================================
+
+/**
+ * Format an ISO date string as a short date: "Mar 16", "Feb 10".
+ */
+export function formatShortDate(isoDate: string): string {
+  const months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
+                  "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+  try {
+    const d = new Date(isoDate);
+    if (isNaN(d.getTime())) return "";
+    return `${months[d.getMonth()]} ${d.getDate()}`;
+  } catch {
+    return "";
+  }
+}
+
+export function formatStatusResponse(
+  state: PluginState,
+  stats: Record<string, unknown>,
+  config: PalaiaPluginConfig,
+): string {
+  const lines: string[] = ["Palaia Memory Status", ""];
+
+  // Recall count
+  const sinceDate = state.firstRecallTimestamp
+    ? formatShortDate(state.firstRecallTimestamp)
+    : "n/a";
+  lines.push(`Recalls: ${state.successfulRecalls} successful (since ${sinceDate})`);
+
+  // Store stats from palaia status --json
+  const totalEntries = stats.total_entries ?? stats.totalEntries ?? "?";
+  const hotEntries = stats.hot ?? stats.hotEntries ?? "?";
+  const warmEntries = stats.warm ?? stats.warmEntries ?? "?";
+  lines.push(`Store: ${totalEntries} entries (${hotEntries} hot, ${warmEntries} warm)`);
+
+  // Recall indicator
+  lines.push(`Recall indicator: ${config.showMemorySources ? "ON" : "OFF"}`);
+
+  // Config summary
+  lines.push(`Config: autoCapture=${config.autoCapture}, captureScope=${config.captureScope || "team"}`);
+
+  return lines.join("\n");
+}

package/src/priorities.ts

@@ -0,0 +1,221 @@
+/**
+ * Injection priority management for multi-agent setups (Issue #121).
+ *
+ * TypeScript-side integration: loads `.palaia/priorities.json`,
+ * resolves layered config (global -> agent -> project), and provides
+ * blocking/filtering utilities for recall injection.
+ *
+ * Mirrors the Python implementation in palaia/priorities.py.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+export interface PrioritiesConfig {
+  version: number;
+  blocked: string[];
+  recallTypeWeight?: Record<string, number>;
+  recallMinScore?: number;
+  maxInjectedChars?: number;
+  tier?: string;
+  agents?: Record<string, AgentPriorityOverride>;
+  projects?: Record<string, ProjectPriorityOverride>;
+}
+
+export interface AgentPriorityOverride {
+  blocked?: string[];
+  recallTypeWeight?: Record<string, number>;
+  recallMinScore?: number;
+  maxInjectedChars?: number;
+  tier?: string;
+}
+
+export interface ProjectPriorityOverride {
+  blocked?: string[];
+  recallTypeWeight?: Record<string, number>;
+}
+
+export interface ResolvedPriorities {
+  blocked: Set<string>;
+  recallTypeWeight: Record<string, number>;
+  recallMinScore: number;
+  maxInjectedChars: number;
+  tier: string;
+}
+
+// ============================================================================
+// Defaults (match Python side)
+// ============================================================================
+
+const DEFAULT_TYPE_WEIGHTS: Record<string, number> = { process: 1.5, task: 1.2, memory: 1.0 };
+const DEFAULT_MIN_SCORE = 0.0;
+const DEFAULT_MAX_CHARS = 4000;
+const DEFAULT_TIER = "hot";
+
+// ============================================================================
+// TTL Cache
+// ============================================================================
+
+const CACHE_TTL_MS = 30_000;
+
+let _cache: {
+  workspace: string;
+  data: PrioritiesConfig | null;
+  loadedAt: number;
+} | null = null;
+
+/** Reset cache (for testing). */
+export function resetPrioritiesCache(): void {
+  _cache = null;
+}
+
+// ============================================================================
+// Load
+// ============================================================================
+
+/**
+ * Load `.palaia/priorities.json` from the given workspace directory.
+ * Returns null if the file does not exist or is invalid.
+ * Results are cached with a 30-second TTL.
+ */
+export async function loadPriorities(workspace: string): Promise<PrioritiesConfig | null> {
+  const now = Date.now();
+  if (_cache && _cache.workspace === workspace && (now - _cache.loadedAt) < CACHE_TTL_MS) {
+    return _cache.data;
+  }
+
+  const path = join(workspace, ".palaia", "priorities.json");
+  let data: PrioritiesConfig | null = null;
+
+  try {
+    const raw = await readFile(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      data = parsed as PrioritiesConfig;
+    }
+  } catch {
+    // File doesn't exist or is invalid — return null
+  }
+
+  _cache = { workspace, data, loadedAt: now };
+  return data;
+}
+
+// ============================================================================
+// Resolve
+// ============================================================================
+
+export interface PriorityDefaults {
+  recallTypeWeight: Record<string, number>;
+  recallMinScore: number;
+  maxInjectedChars: number;
+  tier: string;
+}
+
+/**
+ * Merge priority layers into a flat resolved config.
+ *
+ * Resolution order: plugin defaults -> global overrides -> agent overrides -> project overrides.
+ * `blocked` is a union across all layers.
+ * Type weights are merged (partial overrides fill from previous layer).
+ * Scalar values are overridden (last layer wins).
+ */
+export function resolvePriorities(
+  prio: PrioritiesConfig | null,
+  defaults: PriorityDefaults,
+  agentId?: string,
+  project?: string,
+): ResolvedPriorities {
+  const resolved: ResolvedPriorities = {
+    blocked: new Set<string>(),
+    recallTypeWeight: { ...DEFAULT_TYPE_WEIGHTS, ...defaults.recallTypeWeight },
+    recallMinScore: defaults.recallMinScore ?? DEFAULT_MIN_SCORE,
+    maxInjectedChars: defaults.maxInjectedChars ?? DEFAULT_MAX_CHARS,
+    tier: defaults.tier ?? DEFAULT_TIER,
+  };
+
+  if (!prio) return resolved;
+
+  // Layer 1: Global
+  if (prio.blocked) {
+    for (const b of prio.blocked) resolved.blocked.add(b);
+  }
+  if (prio.recallTypeWeight) {
+    resolved.recallTypeWeight = { ...resolved.recallTypeWeight, ...prio.recallTypeWeight };
+  }
+  if (prio.recallMinScore !== undefined) {
+    resolved.recallMinScore = Number(prio.recallMinScore);
+  }
+  if (prio.maxInjectedChars !== undefined) {
+    resolved.maxInjectedChars = Number(prio.maxInjectedChars);
+  }
+  if (prio.tier !== undefined) {
+    resolved.tier = prio.tier;
+  }
+
+  // Layer 2: Agent override
+  if (agentId) {
+    const agentCfg = prio.agents?.[agentId];
+    if (agentCfg) {
+      if (agentCfg.blocked) {
+        for (const b of agentCfg.blocked) resolved.blocked.add(b);
+      }
+      if (agentCfg.recallTypeWeight) {
+        resolved.recallTypeWeight = { ...resolved.recallTypeWeight, ...agentCfg.recallTypeWeight };
+      }
+      if (agentCfg.recallMinScore !== undefined) {
+        resolved.recallMinScore = Number(agentCfg.recallMinScore);
+      }
+      if (agentCfg.maxInjectedChars !== undefined) {
+        resolved.maxInjectedChars = Number(agentCfg.maxInjectedChars);
+      }
+      if (agentCfg.tier !== undefined) {
+        resolved.tier = agentCfg.tier;
+      }
+    }
+  }
+
+  // Layer 3: Project override (only blocked + recallTypeWeight)
+  if (project) {
+    const projCfg = prio.projects?.[project];
+    if (projCfg) {
+      if (projCfg.blocked) {
+        for (const b of projCfg.blocked) resolved.blocked.add(b);
+      }
+      if (projCfg.recallTypeWeight) {
+        resolved.recallTypeWeight = { ...resolved.recallTypeWeight, ...projCfg.recallTypeWeight };
+      }
+    }
+  }
+
+  return resolved;
+}
+
+// ============================================================================
+// Blocking
+// ============================================================================
+
+/**
+ * Check if an entry ID is blocked (exact or prefix match).
+ * Prefix match requires the blocked prefix to be at least 8 chars.
+ */
+export function isBlocked(entryId: string, blocked: Set<string>): boolean {
+  if (blocked.has(entryId)) return true;
+  for (const b of blocked) {
+    if (b.length >= 8 && entryId.startsWith(b)) return true;
+  }
+  return false;
+}
+
+/**
+ * Filter out blocked entries from a list.
+ * Each entry must have an `id` property.
+ */
+export function filterBlocked<T extends { id: string }>(entries: T[], blocked: Set<string>): T[] {
+  if (blocked.size === 0) return entries;
+  return entries.filter((e) => !isBlocked(e.id, blocked));
+}

package/src/tools.ts

@@ -9,7 +9,8 @@
 import { Type } from "@sinclair/typebox";
 import { run, runJson, type RunnerOpts } from "./runner.js";
 import type { PalaiaPluginConfig } from "./config.js";
-import { sanitizeScope, isValidScope } from "./hooks.js";
+import { sanitizeScope, isValidScope } from "./hooks/index.js";
+import type { OpenClawPluginApi } from "./types.js";
 
 /** Shape returned by `palaia query --json` */
 interface QueryResult {
@@ -62,7 +63,7 @@ function buildRunnerOpts(config: PalaiaPluginConfig): RunnerOpts {
 /**
  * Register all Palaia agent tools on the given plugin API.
  */
-export function registerTools(api: any, config: PalaiaPluginConfig): void {
+export function registerTools(api: OpenClawPluginApi, config: PalaiaPluginConfig): void {
   const opts = buildRunnerOpts(config);
 
   // ── memory_search ──────────────────────────────────────────────

package/src/types.ts

@@ -0,0 +1,119 @@
+/**
+ * OpenClaw Plugin SDK types.
+ *
+ * These interfaces define the contract with OpenClaw's plugin system.
+ * They are maintained locally to avoid a build-time dependency on the
+ * openclaw package (which is a peerDependency loaded at runtime).
+ *
+ * Based on OpenClaw v2026.3.22 plugin-sdk.
+ */
+
+import type { TObject } from "@sinclair/typebox";
+
+// ── Tool Types ──────────────────────────────────────────────────────────
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: TObject;
+  execute(id: string, params: Record<string, unknown>): Promise<ToolResult>;
+}
+
+export interface ToolResult {
+  content: Array<{ type: "text"; text: string }>;
+}
+
+export interface ToolOptions {
+  /** Mark this tool as optional (not registered by default). */
+  optional?: boolean;
+}
+
+export type ToolFactory = ToolDefinition;
+
+// ── Hook Types ──────────────────────────────────────────────────────────
+
+export type HookName =
+  | "before_prompt_build"
+  | "agent_end"
+  | "message_received"
+  | "message_sending";
+
+export type HookHandler = (event: unknown, ctx: unknown) => void | Promise<unknown>;
+
+export interface HookOptions {
+  priority?: number;
+}
+
+// ── Command Types ───────────────────────────────────────────────────────
+
+export interface CommandDefinition {
+  name: string;
+  description: string;
+  handler(args: string): Promise<{ text: string }> | { text: string };
+}
+
+// ── Service Types ───────────────────────────────────────────────────────
+
+export interface ServiceDefinition {
+  id: string;
+  start(): Promise<void>;
+  stop?(): Promise<void>;
+}
+
+// ── Context Engine Types ────────────────────────────────────────────────
+
+export interface ContextEngine {
+  bootstrap?(): Promise<void>;
+  ingest?(messages: unknown[]): Promise<void>;
+  assemble(budget: { maxTokens: number }): Promise<{ content: string; tokenEstimate: number }>;
+  compact?(): Promise<void>;
+  afterTurn?(turn: unknown): Promise<void>;
+  prepareSubagentSpawn?(parentContext: unknown): Promise<unknown>;
+  onSubagentEnded?(result: unknown): Promise<void>;
+}
+
+// ── Logger ──────────────────────────────────────────────────────────────
+
+export interface PluginLogger {
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error?(...args: unknown[]): void;
+  debug?(...args: unknown[]): void;
+}
+
+// ── Runtime ─────────────────────────────────────────────────────────────
+
+export interface PluginRuntime {
+  agent?: {
+    runEmbeddedPiAgent?(params: Record<string, unknown>): Promise<unknown>;
+  };
+  modelAuth?: {
+    resolveApiKeyForProvider(params: {
+      provider: string;
+      cfg: Record<string, unknown>;
+    }): Promise<string | null>;
+  };
+}
+
+// ── Main Plugin API ─────────────────────────────────────────────────────
+
+export interface OpenClawPluginApi {
+  registerTool(definition: ToolDefinition, options?: ToolOptions): void;
+  registerCommand(command: CommandDefinition): void;
+  registerService(service: ServiceDefinition): void;
+  registerContextEngine?(id: string, engine: ContextEngine): void;
+  on(hook: HookName | string, handler: HookHandler): void;
+  getConfig(pluginId: string): Record<string, unknown> | undefined;
+  logger: PluginLogger;
+  runtime: PluginRuntime;
+  config: Record<string, unknown>;
+  workspace?: { dir: string; agentId?: string } | string;
+}
+
+// ── Plugin Entry ────────────────────────────────────────────────────────
+
+export interface OpenClawPluginEntry {
+  id: string;
+  name: string;
+  register(api: OpenClawPluginApi): void | Promise<void>;
+}