@byte5ai/palaia 2.3.6 → 2.7.1

package/src/tools.ts

@@ -1,15 +1,16 @@
 /**
  * Agent tools: memory_search, memory_get, memory_write.
  *
- * These tools are the core of the Palaia OpenClaw integration.
+ * These tools are the core of the palaia OpenClaw integration.
  * They shell out to the palaia CLI with --json and return results
  * in the format OpenClaw agents expect.
  */
 
 import { Type } from "@sinclair/typebox";
-import { run, runJson, type RunnerOpts } from "./runner.js";
+import { run, runJson, getEmbedServerManager, type RunnerOpts } from "./runner.js";
 import type { PalaiaPluginConfig } from "./config.js";
 import { sanitizeScope, isValidScope } from "./hooks/index.js";
+import { loadPriorities, resolvePriorities } from "./priorities.js";
 import type { OpenClawPluginApi } from "./types.js";
 
 /** Shape returned by `palaia query --json` */
@@ -61,7 +62,7 @@ function buildRunnerOpts(config: PalaiaPluginConfig): RunnerOpts {
 }
 
 /**
- * Register all Palaia agent tools on the given plugin API.
+ * Register all palaia agent tools on the given plugin API.
  */
 export function registerTools(api: OpenClawPluginApi, config: PalaiaPluginConfig): void {
   const opts = buildRunnerOpts(config);
@@ -70,7 +71,7 @@ export function registerTools(api: OpenClawPluginApi, config: PalaiaPluginConfig
   api.registerTool({
     name: "memory_search",
     description:
-      "Semantically search Palaia memory for relevant notes and context.",
+      "Semantically search palaia memory for relevant notes and context.",
     parameters: Type.Object({
       query: Type.String({ description: "Search query" }),
       maxResults: Type.Optional(
@@ -81,11 +82,6 @@ export function registerTools(api: OpenClawPluginApi, config: PalaiaPluginConfig
           description: "hot|warm|all (default: hot+warm)",
         })
       ),
-      scope: Type.Optional(
-        Type.String({
-          description: "Filter by scope: private|team|shared:X|public",
-        })
-      ),
       type: Type.Optional(
         Type.String({
           description: "Filter by entry type: memory|process|task",
@@ -98,27 +94,73 @@ export function registerTools(api: OpenClawPluginApi, config: PalaiaPluginConfig
         query: string;
         maxResults?: number;
         tier?: string;
-        scope?: string;
         type?: string;
       }
     ) {
+      // Load scope visibility from priorities (Issue #145: agent isolation)
+      let scopeVisibility: string[] | null = null;
+      try {
+        const prio = await loadPriorities(config.workspace || "");
+        const agentId = process.env.PALAIA_AGENT || undefined;
+        const resolvedPrio = resolvePriorities(prio, {
+          recallTypeWeight: config.recallTypeWeight,
+          recallMinScore: config.recallMinScore,
+          maxInjectedChars: config.maxInjectedChars,
+          tier: config.tier,
+        }, agentId);
+        scopeVisibility = resolvedPrio.scopeVisibility;
+      } catch {
+        // Non-fatal: proceed without scope filtering
+      }
+
       const limit = params.maxResults || config.maxResults || 5;
-      const args: string[] = ["query", params.query, "--limit", String(limit)];
+      const includeCold = params.tier === "all" || config.tier === "all";
 
-      // --all flag includes cold tier
-      if (params.tier === "all" || config.tier === "all") {
-        args.push("--all");
+      // Try embed server first — its queue correctly handles concurrent requests
+      // without counting wait time against the timeout.
+      let result: QueryResult | null = null;
+      if (config.embeddingServer) {
+        try {
+          const mgr = getEmbedServerManager(opts);
+          const resp = await mgr.query({
+            text: params.query,
+            top_k: limit,
+            include_cold: includeCold,
+            ...(params.type ? { type: params.type } : {}),
+          }, config.timeoutMs || 3000);
+          if (resp?.result?.results && Array.isArray(resp.result.results)) {
+            result = { results: resp.result.results };
+          }
+        } catch {
+          // Fall through to CLI
+        }
       }
 
-      // Type filter (Issue #82)
-      if (params.type) {
-        args.push("--type", params.type);
+      // CLI fallback — longer timeout since it includes process spawn overhead
+      if (!result) {
+        const args: string[] = ["query", params.query, "--limit", String(limit)];
+        if (includeCold) {
+          args.push("--all");
+        }
+        if (params.type) {
+          args.push("--type", params.type);
+        }
+        result = await runJson<QueryResult>(args, { ...opts, timeoutMs: 15000 });
       }
 
-      const result = await runJson<QueryResult>(args, opts);
+      // Apply scope visibility filter (Issue #145: agent isolation)
+      let filteredResults = result.results || [];
+      if (scopeVisibility) {
+        filteredResults = filteredResults.filter((r) => {
+          const scope = r.scope || "team";
+          // Legacy shared:X entries are treated as team
+          const effectiveScope = scope.startsWith("shared:") ? "team" : scope;
+          return scopeVisibility!.includes(effectiveScope);
+        });
+      }
 
       // Format as memory_search compatible output
-      const snippets = (result.results || []).map((r) => {
+      const snippets = filteredResults.map((r) => {
         const body = r.content || r.body || "";
         const path = r.path || `${r.tier}/${r.id}.md`;
         return {
@@ -149,7 +191,7 @@ export function registerTools(api: OpenClawPluginApi, config: PalaiaPluginConfig
   // ── memory_get ─────────────────────────────────────────────────
   api.registerTool({
     name: "memory_get",
-    description: "Read a specific Palaia memory entry by path or id.",
+    description: "Read a specific palaia memory entry by path or id.",
     parameters: Type.Object({
       path: Type.String({ description: "Memory path or UUID" }),
       from: Type.Optional(
@@ -189,12 +231,12 @@ export function registerTools(api: OpenClawPluginApi, config: PalaiaPluginConfig
     {
       name: "memory_write",
       description:
-        "Write a new memory entry to Palaia. WAL-backed, crash-safe.",
+        "Write a new memory entry to palaia. WAL-backed, crash-safe.",
       parameters: Type.Object({
         content: Type.String({ description: "Memory content to write" }),
         scope: Type.Optional(
           Type.String({
-            description: "Scope: private|team|shared:X|public (default: team)",
+            description: "Scope: private|team|public (default: team)",
             default: "team",
           })
         ),
@@ -282,7 +324,7 @@ export function registerTools(api: OpenClawPluginApi, config: PalaiaPluginConfig
               content: [
                 {
                   type: "text" as const,
-                  text: `Invalid scope "${params.scope}". Valid scopes: private, team, public, shared:<name>`,
+                  text: `Invalid scope "${params.scope}". Valid scopes: private, team, public`,
                 },
               ],
             };

package/src/types.ts

@@ -5,7 +5,7 @@
  * 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.
+ * Based on OpenClaw v2026.3.28 plugin-sdk.
  */
 
 import type { TObject } from "@sinclair/typebox";
@@ -28,23 +28,230 @@ export interface ToolOptions {
   optional?: boolean;
 }
 
-export type ToolFactory = ToolDefinition;
+export type ToolFactory = ToolDefinition | ((ctx: Record<string, unknown>) => ToolDefinition | ToolDefinition[] | null);
 
-// ── Hook Types ──────────────────────────────────────────────────────────
+// ── Hook Types ─────────────��────────────────────────────────────────────
 
+/**
+ * All hook names supported by OpenClaw v2026.3.28.
+ * palaia registers handlers for a subset of these.
+ */
 export type HookName =
+  // Session lifecycle
+  | "session_start"
+  | "session_end"
+  // Agent & LLM
+  | "before_model_resolve"
   | "before_prompt_build"
+  | "before_agent_start"
+  | "llm_input"
+  | "llm_output"
   | "agent_end"
+  // Context management
+  | "before_compaction"
+  | "after_compaction"
+  | "before_reset"
+  // Messages
+  | "inbound_claim"
+  | "before_dispatch"
   | "message_received"
-  | "message_sending";
+  | "message_sending"
+  | "message_sent"
+  // Tool execution
+  | "before_tool_call"
+  | "after_tool_call"
+  | "tool_result_persist"
+  | "before_message_write"
+  // Subagents
+  | "subagent_spawning"
+  | "subagent_delivery_target"
+  | "subagent_spawned"
+  | "subagent_ended"
+  // Gateway
+  | "gateway_start"
+  | "gateway_stop";
 
-export type HookHandler = (event: unknown, ctx: unknown) => void | Promise<unknown>;
+export type HookHandler = (event: unknown, ctx: unknown) => unknown | Promise<unknown>;
 
 export interface HookOptions {
   priority?: number;
 }
 
-// ── Command Types ───────────────────────────────────────────────────────
+// ── Hook Event Types ────────────────────────────────────────────────────
+
+/** session_start event. */
+export type SessionStartEvent = {
+  sessionId: string;
+  sessionKey?: string;
+  resumedFrom?: string;
+};
+
+/** session_end event. */
+export type SessionEndEvent = {
+  sessionId: string;
+  sessionKey?: string;
+  messageCount: number;
+  durationMs?: number;
+};
+
+/** before_prompt_build event. */
+export type BeforePromptBuildEvent = {
+  prompt: string;
+  messages: unknown[];
+};
+
+/** before_prompt_build result. */
+export type BeforePromptBuildResult = {
+  systemPrompt?: string;
+  prependContext?: string;
+  prependSystemContext?: string;
+  appendSystemContext?: string;
+};
+
+/** before_reset event. */
+export type BeforeResetEvent = {
+  sessionFile?: string;
+  messages?: unknown[];
+  reason?: string;
+};
+
+/** agent_end event. */
+export type AgentEndEvent = {
+  messages: unknown[];
+  success: boolean;
+  error?: string;
+  durationMs?: number;
+};
+
+/** llm_input event — fired before each LLM call. */
+export type LlmInputEvent = {
+  runId: string;
+  sessionId: string;
+  provider: string;
+  model: string;
+  systemPrompt?: string;
+  prompt: string;
+  historyMessages: unknown[];
+  imagesCount: number;
+};
+
+/** llm_output event — fired after each LLM response. */
+export type LlmOutputEvent = {
+  runId: string;
+  sessionId: string;
+  provider: string;
+  model: string;
+  assistantTexts: string[];
+  lastAssistant?: unknown;
+  usage?: {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    total?: number;
+  };
+};
+
+/** after_tool_call event. */
+export type AfterToolCallEvent = {
+  toolName: string;
+  params: Record<string, unknown>;
+  runId?: string;
+  toolCallId?: string;
+  result?: unknown;
+  error?: string;
+  durationMs?: number;
+};
+
+/** message_received event. */
+export type MessageReceivedEvent = {
+  from: string;
+  content: string;
+  timestamp?: number;
+  metadata?: Record<string, unknown>;
+};
+
+/** message_sending event. */
+export type MessageSendingEvent = {
+  to: string;
+  content: string;
+  metadata?: Record<string, unknown>;
+};
+
+/** message_sending result. */
+export type MessageSendingResult = {
+  content?: string;
+  cancel?: boolean;
+};
+
+/** subagent_spawning event. */
+export type SubagentSpawningEvent = {
+  childSessionKey: string;
+  agentId: string;
+  label?: string;
+  mode: "run" | "session";
+  requester?: {
+    channel?: string;
+    accountId?: string;
+    to?: string;
+    threadId?: string | number;
+  };
+  threadRequested: boolean;
+};
+
+/** subagent_ended event. */
+export type SubagentEndedEvent = {
+  targetSessionKey: string;
+  targetKind: "subagent" | "acp";
+  reason: string;
+  sendFarewell?: boolean;
+  accountId?: string;
+  runId?: string;
+  endedAt?: number;
+  outcome?: "ok" | "error" | "timeout" | "killed" | "reset" | "deleted";
+  error?: string;
+};
+
+// ── Hook Context Types ──────────────��───────────────────────────────────
+
+export type AgentContext = {
+  agentId?: string;
+  sessionKey?: string;
+  sessionId?: string;
+  workspaceDir?: string;
+  messageProvider?: string;
+  trigger?: string;
+  channelId?: string;
+};
+
+export type MessageContext = {
+  channelId: string;
+  accountId?: string;
+  conversationId?: string;
+};
+
+export type SessionContext = {
+  agentId?: string;
+  sessionId: string;
+  sessionKey?: string;
+};
+
+export type ToolContext = {
+  agentId?: string;
+  sessionKey?: string;
+  sessionId?: string;
+  runId?: string;
+  toolName: string;
+  toolCallId?: string;
+};
+
+export type SubagentContext = {
+  runId?: string;
+  childSessionKey?: string;
+  requesterSessionKey?: string;
+};
+
+// ── Command Types ───���───────────────────────────────────────────────────
 
 export interface CommandDefinition {
   name: string;
@@ -52,17 +259,156 @@ export interface CommandDefinition {
   handler(args: string): Promise<{ text: string }> | { text: string };
 }
 
-// ── Service Types ───────────────────────────────────────────────────────
+// ── Service Types ─────────────────────────────────────���─────────────────
+
+export interface ServiceContext {
+  config: Record<string, unknown>;
+  workspaceDir?: string;
+  stateDir: string;
+  logger: PluginLogger;
+}
 
 export interface ServiceDefinition {
   id: string;
-  start(): Promise<void>;
-  stop?(): Promise<void>;
+  start(ctx: ServiceContext): Promise<void>;
+  stop?(ctx: ServiceContext): Promise<void>;
 }
 
-// ── Context Engine Types ────────────────────────────────────────────────
+// ���─ Context Engine Types ────────────���───────────────────────────────────
+
+/** Opaque message type from OpenClaw's agent runtime. */
+export type AgentMessage = unknown;
+
+export interface ContextEngineInfo {
+  id: string;
+  name: string;
+  version?: string;
+  ownsCompaction?: boolean;
+}
 
+export type BootstrapResult = {
+  bootstrapped: boolean;
+  importedMessages?: number;
+  reason?: string;
+};
+
+export type IngestResult = {
+  ingested: boolean;
+};
+
+export type AssembleResult = {
+  messages: AgentMessage[];
+  estimatedTokens: number;
+  systemPromptAddition?: string;
+};
+
+export type CompactResult = {
+  ok: boolean;
+  compacted: boolean;
+  reason?: string;
+  result?: {
+    summary?: string;
+    firstKeptEntryId?: string;
+    tokensBefore: number;
+    tokensAfter?: number;
+    details?: unknown;
+  };
+};
+
+export type SubagentSpawnPreparation = {
+  rollback: () => void | Promise<void>;
+};
+
+export type SubagentEndReason = "deleted" | "completed" | "swept" | "released";
+
+/**
+ * ContextEngine interface — matches OpenClaw v2026.3.28.
+ *
+ * This is the full interface. palaia implements a subset;
+ * optional methods are marked with `?`.
+ */
 export interface ContextEngine {
+  readonly info: ContextEngineInfo;
+
+  bootstrap?(params: {
+    sessionId: string;
+    sessionKey?: string;
+    sessionFile: string;
+  }): Promise<BootstrapResult>;
+
+  maintain?(params: {
+    sessionId: string;
+    sessionKey?: string;
+    sessionFile: string;
+    runtimeContext?: Record<string, unknown>;
+  }): Promise<unknown>;
+
+  ingest(params: {
+    sessionId: string;
+    sessionKey?: string;
+    message: AgentMessage;
+    isHeartbeat?: boolean;
+  }): Promise<IngestResult>;
+
+  ingestBatch?(params: {
+    sessionId: string;
+    sessionKey?: string;
+    messages: AgentMessage[];
+    isHeartbeat?: boolean;
+  }): Promise<{ ingestedCount: number }>;
+
+  afterTurn?(params: {
+    sessionId: string;
+    sessionKey?: string;
+    sessionFile: string;
+    messages: AgentMessage[];
+    prePromptMessageCount: number;
+    autoCompactionSummary?: string;
+    isHeartbeat?: boolean;
+    tokenBudget?: number;
+    runtimeContext?: Record<string, unknown>;
+  }): Promise<void>;
+
+  assemble(params: {
+    sessionId: string;
+    sessionKey?: string;
+    messages: AgentMessage[];
+    tokenBudget?: number;
+    model?: string;
+    prompt?: string;
+  }): Promise<AssembleResult>;
+
+  compact(params: {
+    sessionId: string;
+    sessionKey?: string;
+    sessionFile: string;
+    tokenBudget?: number;
+    force?: boolean;
+    currentTokenCount?: number;
+    compactionTarget?: "budget" | "threshold";
+    customInstructions?: string;
+    runtimeContext?: Record<string, unknown>;
+  }): Promise<CompactResult>;
+
+  prepareSubagentSpawn?(params: {
+    parentSessionKey: string;
+    childSessionKey: string;
+    ttlMs?: number;
+  }): Promise<SubagentSpawnPreparation | undefined>;
+
+  onSubagentEnded?(params: {
+    childSessionKey: string;
+    reason: SubagentEndReason;
+  }): Promise<void>;
+
+  dispose?(): Promise<void>;
+}
+
+/**
+ * Legacy ContextEngine interface for backward compatibility.
+ * Used when OpenClaw < 2026.3.24 registers via the old signature.
+ */
+export interface LegacyContextEngine {
   bootstrap?(): Promise<void>;
   ingest?(messages: unknown[]): Promise<void>;
   assemble(budget: { maxTokens: number }): Promise<{ content: string; tokenEstimate: number }>;
@@ -72,45 +418,86 @@ export interface ContextEngine {
   onSubagentEnded?(result: unknown): Promise<void>;
 }
 
-// ── Logger ──────────────────────────────────────────────────────────────
+export type ContextEngineFactory = () => ContextEngine | Promise<ContextEngine>;
+
+// ── Memory Prompt Section ───────────────────────────────────────────────
+
+export type MemoryPromptSectionBuilder = (params: {
+  availableTools: Set<string>;
+  citationsMode?: string;
+}) => string[];
+
+// ── Logger ──────────────���───────────────────────────────────────────────
 
 export interface PluginLogger {
-  info(...args: unknown[]): void;
-  warn(...args: unknown[]): void;
-  error?(...args: unknown[]): void;
-  debug?(...args: unknown[]): void;
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  debug?(message: string): void;
 }
 
-// ── Runtime ─────────────────────────────────────────────────────────────
+// ���─ Runtime ───────────────��─────────────────────────────���───────────────
 
 export interface PluginRuntime {
+  version?: string;
   agent?: {
     runEmbeddedPiAgent?(params: Record<string, unknown>): Promise<unknown>;
+    session?: {
+      resolveStorePath?(...args: unknown[]): string;
+      loadSessionStore?(...args: unknown[]): Promise<unknown>;
+    };
+  };
+  subagent?: {
+    run?(params: {
+      sessionKey: string;
+      message: string;
+      provider?: string;
+      model?: string;
+      extraSystemPrompt?: string;
+    }): Promise<{ runId: string }>;
+    getSessionMessages?(params: {
+      sessionKey: string;
+      limit?: number;
+    }): Promise<{ messages: unknown[] }>;
   };
   modelAuth?: {
     resolveApiKeyForProvider(params: {
       provider: string;
-      cfg: Record<string, unknown>;
+      cfg?: Record<string, unknown>;
     }): Promise<string | null>;
   };
+  system?: {
+    requestHeartbeatNow?(): void;
+  };
+  events?: {
+    onSessionTranscriptUpdate?(handler: (event: unknown) => void): void;
+  };
 }
 
 // ── Main Plugin API ─────────────────────────────────────────────────────
 
 export interface OpenClawPluginApi {
-  registerTool(definition: ToolDefinition, options?: ToolOptions): void;
+  id: string;
+  name: string;
+  version?: string;
+  source?: string;
+  registrationMode?: string;
+
+  registerTool(definition: ToolDefinition | ToolFactory, 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;
+  registerContextEngine?(id: string, factory: ContextEngineFactory): void;
+  registerMemoryPromptSection?(builder: MemoryPromptSectionBuilder): void;
+  registerHook?(events: string | string[], handler: HookHandler, opts?: HookOptions): void;
+  on(hook: HookName | string, handler: HookHandler, opts?: HookOptions): void;
   logger: PluginLogger;
   runtime: PluginRuntime;
   config: Record<string, unknown>;
+  pluginConfig?: Record<string, unknown>;
   workspace?: { dir: string; agentId?: string } | string;
 }
 
-// ── Plugin Entry ────────────────────────────────────────────────────────
+// ── Plugin Entry ────────���───────────────────────────────────────────────
 
 export interface OpenClawPluginEntry {
   id: string;