@agentmemory/agentmemory 0.7.0

package/src/functions/sentinels.ts

@@ -0,0 +1,417 @@
+import type { ISdk } from "iii-sdk";
+import type { StateKV } from "../state/kv.js";
+import { KV, generateId } from "../state/schema.js";
+import { withKeyedLock } from "../state/keyed-mutex.js";
+import type { Action, ActionEdge, Checkpoint, CompressedObservation, FunctionMetrics, Sentinel, Session } from "../types.js";
+
+const VALID_TYPES: Sentinel["type"][] = [
+  "webhook",
+  "timer",
+  "threshold",
+  "pattern",
+  "approval",
+  "custom",
+];
+
+export function registerSentinelsFunction(sdk: ISdk, kv: StateKV): void {
+  sdk.registerFunction(
+    { id: "mem::sentinel-create" },
+    async (data: {
+      name: string;
+      type: Sentinel["type"];
+      config?: Record<string, unknown>;
+      linkedActionIds?: string[];
+      expiresInMs?: number;
+    }) => {
+      if (!data.name || typeof data.name !== "string") {
+        return { success: false, error: "name is required" };
+      }
+      if (!data.type || !VALID_TYPES.includes(data.type)) {
+        return {
+          success: false,
+          error: `type must be one of: ${VALID_TYPES.join(", ")}`,
+        };
+      }
+
+      if (data.type === "threshold") {
+        const cfg = data.config as
+          | { metric?: string; operator?: string; value?: number }
+          | undefined;
+        if (
+          !cfg ||
+          !cfg.metric ||
+          !["gt", "lt", "eq"].includes(cfg.operator || "") ||
+          typeof cfg.value !== "number"
+        ) {
+          return {
+            success: false,
+            error:
+              "threshold config requires metric, operator (gt|lt|eq), and numeric value",
+          };
+        }
+      }
+
+      if (data.type === "pattern") {
+        const cfg = data.config as { pattern?: string } | undefined;
+        if (!cfg || !cfg.pattern || typeof cfg.pattern !== "string") {
+          return {
+            success: false,
+            error: "pattern config requires a pattern string",
+          };
+        }
+      }
+
+      if (data.type === "webhook") {
+        const cfg = data.config as { path?: string } | undefined;
+        if (!cfg || !cfg.path || typeof cfg.path !== "string") {
+          return {
+            success: false,
+            error: "webhook config requires a path string",
+          };
+        }
+      }
+
+      if (data.type === "timer") {
+        const cfg = data.config as { durationMs?: number } | undefined;
+        if (!cfg || typeof cfg.durationMs !== "number" || cfg.durationMs <= 0) {
+          return {
+            success: false,
+            error: "timer config requires a positive durationMs",
+          };
+        }
+      }
+
+      if (data.linkedActionIds && data.linkedActionIds.length > 0) {
+        for (const actionId of data.linkedActionIds) {
+          const action = await kv.get<Action>(KV.actions, actionId);
+          if (!action) {
+            return {
+              success: false,
+              error: `linked action not found: ${actionId}`,
+            };
+          }
+        }
+      }
+
+      const now = new Date();
+      const sentinel: Sentinel = {
+        id: generateId("snl"),
+        name: data.name.trim(),
+        type: data.type,
+        status: "watching",
+        config: data.config || {},
+        createdAt: now.toISOString(),
+        linkedActionIds: data.linkedActionIds || [],
+        expiresAt: data.expiresInMs
+          ? new Date(now.getTime() + data.expiresInMs).toISOString()
+          : undefined,
+      };
+
+      await kv.set(KV.sentinels, sentinel.id, sentinel);
+
+      if (data.linkedActionIds && data.linkedActionIds.length > 0) {
+        for (const actionId of data.linkedActionIds) {
+          const edge: ActionEdge = {
+            id: generateId("ae"),
+            type: "gated_by",
+            sourceActionId: actionId,
+            targetActionId: sentinel.id,
+            createdAt: now.toISOString(),
+          };
+          await kv.set(KV.actionEdges, edge.id, edge);
+        }
+      }
+
+      if (data.type === "timer") {
+        const durationMs = (data.config as { durationMs: number }).durationMs;
+        setTimeout(async () => {
+          await withKeyedLock(`mem:sentinel:${sentinel.id}`, async () => {
+            const fresh = await kv.get<Sentinel>(KV.sentinels, sentinel.id);
+            if (!fresh || fresh.status !== "watching") return;
+            fresh.status = "triggered";
+            fresh.triggeredAt = new Date().toISOString();
+            fresh.result = { reason: "timer_elapsed", durationMs };
+            await kv.set(KV.sentinels, fresh.id, fresh);
+            await unblockLinkedActions(kv, fresh);
+          });
+        }, durationMs);
+      }
+
+      return { success: true, sentinel };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::sentinel-trigger" },
+    async (data: { sentinelId: string; result?: unknown }) => {
+      if (!data.sentinelId) {
+        return { success: false, error: "sentinelId is required" };
+      }
+
+      return withKeyedLock(
+        `mem:sentinel:${data.sentinelId}`,
+        async () => {
+          const sentinel = await kv.get<Sentinel>(
+            KV.sentinels,
+            data.sentinelId,
+          );
+          if (!sentinel) {
+            return { success: false, error: "sentinel not found" };
+          }
+          if (sentinel.status !== "watching") {
+            return {
+              success: false,
+              error: `sentinel already ${sentinel.status}`,
+            };
+          }
+
+          sentinel.status = "triggered";
+          sentinel.triggeredAt = new Date().toISOString();
+          sentinel.result = data.result;
+
+          await kv.set(KV.sentinels, sentinel.id, sentinel);
+
+          let unblockedCount = 0;
+          if (sentinel.linkedActionIds.length > 0) {
+            unblockedCount = await unblockLinkedActions(kv, sentinel);
+          }
+
+          return { success: true, sentinel, unblockedCount };
+        },
+      );
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::sentinel-check" },
+    async () => {
+      const sentinels = await kv.list<Sentinel>(KV.sentinels);
+      const active = sentinels.filter((s) => s.status === "watching");
+      const triggered: string[] = [];
+
+      for (const sentinel of active) {
+        if (sentinel.type === "threshold") {
+          const cfg = sentinel.config as {
+            metric: string;
+            operator: "gt" | "lt" | "eq";
+            value: number;
+          };
+          const metrics = await kv.get<FunctionMetrics>(
+            KV.metrics,
+            cfg.metric,
+          );
+          if (!metrics) continue;
+
+          const current = metrics.totalCalls;
+          let matched = false;
+          if (cfg.operator === "gt") matched = current > cfg.value;
+          else if (cfg.operator === "lt") matched = current < cfg.value;
+          else if (cfg.operator === "eq") matched = current === cfg.value;
+
+          if (matched) {
+            await withKeyedLock(
+              `mem:sentinel:${sentinel.id}`,
+              async () => {
+                const fresh = await kv.get<Sentinel>(
+                  KV.sentinels,
+                  sentinel.id,
+                );
+                if (!fresh || fresh.status !== "watching") return;
+                fresh.status = "triggered";
+                fresh.triggeredAt = new Date().toISOString();
+                fresh.result = {
+                  reason: "threshold_crossed",
+                  metric: cfg.metric,
+                  currentValue: current,
+                  threshold: cfg.value,
+                  operator: cfg.operator,
+                };
+                await kv.set(KV.sentinels, fresh.id, fresh);
+                await unblockLinkedActions(kv, fresh);
+              },
+            );
+            triggered.push(sentinel.id);
+          }
+        }
+
+        if (sentinel.type === "pattern") {
+          const cfg = sentinel.config as { pattern: string };
+          const regex = new RegExp(cfg.pattern, "i");
+          const sessions = await kv.list<Session>(KV.sessions);
+          let matchedObs: CompressedObservation | null = null;
+
+          for (const session of sessions) {
+            const observations = await kv.list<CompressedObservation>(
+              KV.observations(session.id),
+            );
+            const recent = observations
+              .filter(
+                (o) =>
+                  new Date(o.timestamp).getTime() >=
+                  new Date(sentinel.createdAt).getTime(),
+              )
+              .find((o) => regex.test(o.title));
+            if (recent) {
+              matchedObs = recent;
+              break;
+            }
+          }
+
+          if (matchedObs) {
+            await withKeyedLock(
+              `mem:sentinel:${sentinel.id}`,
+              async () => {
+                const fresh = await kv.get<Sentinel>(
+                  KV.sentinels,
+                  sentinel.id,
+                );
+                if (!fresh || fresh.status !== "watching") return;
+                fresh.status = "triggered";
+                fresh.triggeredAt = new Date().toISOString();
+                fresh.result = {
+                  reason: "pattern_matched",
+                  pattern: cfg.pattern,
+                  matchedObservationId: matchedObs!.id,
+                  matchedTitle: matchedObs!.title,
+                };
+                await kv.set(KV.sentinels, fresh.id, fresh);
+                await unblockLinkedActions(kv, fresh);
+              },
+            );
+            triggered.push(sentinel.id);
+          }
+        }
+      }
+
+      return { success: true, triggered, checkedCount: active.length };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::sentinel-cancel" },
+    async (data: { sentinelId: string }) => {
+      if (!data.sentinelId) {
+        return { success: false, error: "sentinelId is required" };
+      }
+
+      return withKeyedLock(
+        `mem:sentinel:${data.sentinelId}`,
+        async () => {
+          const sentinel = await kv.get<Sentinel>(
+            KV.sentinels,
+            data.sentinelId,
+          );
+          if (!sentinel) {
+            return { success: false, error: "sentinel not found" };
+          }
+          if (sentinel.status !== "watching") {
+            return {
+              success: false,
+              error: `cannot cancel sentinel with status ${sentinel.status}`,
+            };
+          }
+
+          sentinel.status = "cancelled";
+          await kv.set(KV.sentinels, sentinel.id, sentinel);
+
+          return { success: true, sentinel };
+        },
+      );
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::sentinel-list" },
+    async (data: { status?: string; type?: string }) => {
+      let sentinels = await kv.list<Sentinel>(KV.sentinels);
+
+      if (data.status) {
+        sentinels = sentinels.filter((s) => s.status === data.status);
+      }
+      if (data.type) {
+        sentinels = sentinels.filter((s) => s.type === data.type);
+      }
+
+      sentinels.sort(
+        (a, b) =>
+          new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
+      );
+
+      return { success: true, sentinels };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::sentinel-expire" },
+    async () => {
+      const sentinels = await kv.list<Sentinel>(KV.sentinels);
+      const now = Date.now();
+      let expired = 0;
+
+      for (const sentinel of sentinels) {
+        if (
+          sentinel.status === "watching" &&
+          sentinel.expiresAt &&
+          new Date(sentinel.expiresAt).getTime() <= now
+        ) {
+          const didExpire = await withKeyedLock(
+            `mem:sentinel:${sentinel.id}`,
+            async () => {
+              const fresh = await kv.get<Sentinel>(
+                KV.sentinels,
+                sentinel.id,
+              );
+              if (!fresh || fresh.status !== "watching") return false;
+              fresh.status = "expired";
+              fresh.triggeredAt = new Date().toISOString();
+              await kv.set(KV.sentinels, fresh.id, fresh);
+              return true;
+            },
+          );
+          if (didExpire) expired++;
+        }
+      }
+
+      return { success: true, expired };
+    },
+  );
+}
+
+async function unblockLinkedActions(
+  kv: StateKV,
+  sentinel: Sentinel,
+): Promise<number> {
+  if (sentinel.linkedActionIds.length === 0) return 0;
+
+  const allEdges = await kv.list<ActionEdge>(KV.actionEdges);
+  const allSentinels = await kv.list<Sentinel>(KV.sentinels);
+  const allCheckpoints = await kv.list<Checkpoint>(KV.checkpoints);
+  const gateMap = new Map<string, { status: string }>();
+  for (const s of allSentinels) gateMap.set(s.id, { status: s.status === "triggered" ? "passed" : s.status });
+  for (const c of allCheckpoints) gateMap.set(c.id, { status: c.status });
+
+  let unblockedCount = 0;
+
+  for (const actionId of sentinel.linkedActionIds) {
+    await withKeyedLock(`mem:action:${actionId}`, async () => {
+      const action = await kv.get<Action>(KV.actions, actionId);
+      if (action && action.status === "blocked") {
+        const gates = allEdges.filter(
+          (e) => e.sourceActionId === actionId && e.type === "gated_by",
+        );
+        const allPassed = gates.every((g) => {
+          const gate = gateMap.get(g.targetActionId);
+          return gate && gate.status === "passed";
+        });
+        if (allPassed) {
+          action.status = "pending";
+          action.updatedAt = new Date().toISOString();
+          await kv.set(KV.actions, action.id, action);
+          unblockedCount++;
+        }
+      }
+    });
+  }
+
+  return unblockedCount;
+}

package/src/functions/signals.ts

@@ -0,0 +1,186 @@
+import type { ISdk } from "iii-sdk";
+import type { StateKV } from "../state/kv.js";
+import { KV, generateId } from "../state/schema.js";
+import type { Signal } from "../types.js";
+
+export function registerSignalsFunction(sdk: ISdk, kv: StateKV): void {
+  sdk.registerFunction(
+    { id: "mem::signal-send" },
+    async (data: {
+      from: string;
+      to?: string;
+      content: string;
+      type?: Signal["type"];
+      threadId?: string;
+      replyTo?: string;
+      metadata?: Record<string, unknown>;
+      expiresInMs?: number;
+    }) => {
+      if (!data.from?.trim() || !data.content?.trim()) {
+        return { success: false, error: "from and non-empty content are required" };
+      }
+
+      const now = new Date();
+      let threadId = data.threadId;
+
+      if (data.replyTo && !threadId) {
+        const parent = await kv.get<Signal>(KV.signals, data.replyTo);
+        if (parent) {
+          threadId = parent.threadId || parent.id;
+        }
+      }
+
+      const signal: Signal = {
+        id: generateId("sig"),
+        from: data.from,
+        to: data.to,
+        content: data.content.trim(),
+        type: data.type || "info",
+        threadId: threadId || generateId("thr"),
+        replyTo: data.replyTo,
+        metadata: data.metadata,
+        createdAt: now.toISOString(),
+        expiresAt: data.expiresInMs
+          ? new Date(now.getTime() + data.expiresInMs).toISOString()
+          : undefined,
+      };
+
+      await kv.set(KV.signals, signal.id, signal);
+
+      return { success: true, signal };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::signal-read" },
+    async (data: {
+      agentId: string;
+      unreadOnly?: boolean;
+      threadId?: string;
+      type?: string;
+      limit?: number;
+    }) => {
+      if (!data.agentId) {
+        return { success: false, error: "agentId is required" };
+      }
+
+      let signals = await kv.list<Signal>(KV.signals);
+      const now = Date.now();
+
+      signals = signals.filter((s) => {
+        if (s.expiresAt && new Date(s.expiresAt).getTime() <= now) return false;
+        if (s.to && s.to !== data.agentId && s.from !== data.agentId)
+          return false;
+        if (!s.to && s.from !== data.agentId) return true;
+        return true;
+      });
+
+      if (data.unreadOnly) {
+        signals = signals.filter((s) => !s.readAt && s.to === data.agentId);
+      }
+      if (data.threadId) {
+        signals = signals.filter((s) => s.threadId === data.threadId);
+      }
+      if (data.type) {
+        signals = signals.filter((s) => s.type === data.type);
+      }
+
+      signals.sort(
+        (a, b) =>
+          new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
+      );
+
+      const limit = data.limit || 50;
+      const results = signals.slice(0, limit);
+
+      for (const sig of results) {
+        if (!sig.readAt && sig.to === data.agentId) {
+          sig.readAt = new Date().toISOString();
+          await kv.set(KV.signals, sig.id, sig);
+        }
+      }
+
+      return { success: true, signals: results };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::signal-threads" },
+    async (data: { agentId: string; limit?: number }) => {
+      if (!data.agentId) {
+        return { success: false, error: "agentId is required" };
+      }
+
+      const signals = await kv.list<Signal>(KV.signals);
+      const now = Date.now();
+
+      const relevant = signals.filter((s) => {
+        if (s.expiresAt && new Date(s.expiresAt).getTime() <= now) return false;
+        return (
+          s.from === data.agentId ||
+          s.to === data.agentId ||
+          !s.to
+        );
+      });
+
+      const threadMap = new Map<
+        string,
+        { threadId: string; messages: number; lastMessage: string; participants: Set<string> }
+      >();
+
+      for (const sig of relevant) {
+        const tid = sig.threadId || sig.id;
+        const existing = threadMap.get(tid);
+        if (existing) {
+          existing.messages++;
+          existing.participants.add(sig.from);
+          if (sig.to) existing.participants.add(sig.to);
+          if (new Date(sig.createdAt) > new Date(existing.lastMessage)) {
+            existing.lastMessage = sig.createdAt;
+          }
+        } else {
+          const participants = new Set<string>([sig.from]);
+          if (sig.to) participants.add(sig.to);
+          threadMap.set(tid, {
+            threadId: tid,
+            messages: 1,
+            lastMessage: sig.createdAt,
+            participants,
+          });
+        }
+      }
+
+      const threads = Array.from(threadMap.values())
+        .map((t) => ({
+          ...t,
+          participants: Array.from(t.participants),
+        }))
+        .sort(
+          (a, b) =>
+            new Date(b.lastMessage).getTime() -
+            new Date(a.lastMessage).getTime(),
+        )
+        .slice(0, data.limit || 20);
+
+      return { success: true, threads };
+    },
+  );
+
+  sdk.registerFunction(
+    { id: "mem::signal-cleanup" },
+    async () => {
+      const signals = await kv.list<Signal>(KV.signals);
+      const now = Date.now();
+      let removed = 0;
+
+      for (const sig of signals) {
+        if (sig.expiresAt && new Date(sig.expiresAt).getTime() <= now) {
+          await kv.delete(KV.signals, sig.id);
+          removed++;
+        }
+      }
+
+      return { success: true, removed };
+    },
+  );
+}