Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

10.1 KB
Raw Blame
import type { IIIClient } 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, Sketch } from "../types.js";
import { safeAudit } from "./audit.js";

export function registerSketchesFunction(sdk: IIIClient, kv: StateKV): void {
  sdk.registerFunction("mem::sketch-create", 
    async (data: {
      title: string;
      description?: string;
      expiresInMs?: number;
      project?: string;
    }) => {
      if (!data.title || typeof data.title !== "string") {
        return { success: false, error: "title is required" };
      }

      const now = new Date();
      const expiresInMs = data.expiresInMs || 3600000;
      const sketch: Sketch = {
        id: generateId("sk"),
        title: data.title.trim(),
        description: (data.description || "").trim(),
        status: "active",
        actionIds: [],
        project: data.project,
        createdAt: now.toISOString(),
        expiresAt: new Date(now.getTime() + expiresInMs).toISOString(),
      };

      await kv.set(KV.sketches, sketch.id, sketch);
      await safeAudit(kv, "sketch_create", "mem::sketch-create", [sketch.id], {
        action: "create",
        title: sketch.title,
      });
      return { success: true, sketch };
    },
  );

  sdk.registerFunction("mem::sketch-add", 
    async (data: {
      sketchId: string;
      title: string;
      description?: string;
      priority?: number;
      dependsOn?: string[];
    }) => {
      if (!data.sketchId) {
        return { success: false, error: "sketchId is required" };
      }
      if (!data.title || typeof data.title !== "string") {
        return { success: false, error: "title is required" };
      }

      return withKeyedLock(`mem:sketch:${data.sketchId}`, async () => {
        const sketch = await kv.get<Sketch>(KV.sketches, data.sketchId);
        if (!sketch) {
          return { success: false, error: "sketch not found" };
        }
        if (sketch.status !== "active") {
          return { success: false, error: "sketch is not active" };
        }

        const now = new Date().toISOString();
        const action: Action = {
          id: generateId("act"),
          title: data.title.trim(),
          description: (data.description || "").trim(),
          status: "pending",
          priority: Math.max(1, Math.min(10, data.priority || 5)),
          createdAt: now,
          updatedAt: now,
          createdBy: "sketch",
          project: sketch.project,
          tags: [],
          sourceObservationIds: [],
          sourceMemoryIds: [],
          sketchId: data.sketchId,
        };

        if (data.dependsOn && data.dependsOn.length > 0) {
          const sketchActionSet = new Set(sketch.actionIds);
          for (const depId of data.dependsOn) {
            if (!sketchActionSet.has(depId)) {
              return {
                success: false,
                error: `dependency ${depId} not found in this sketch`,
              };
            }
          }
        }

        await kv.set(KV.actions, action.id, action);
        await safeAudit(kv, "sketch_create", "mem::sketch-add", [action.id], {
          action: "add.action",
          sketchId: sketch.id,
        });

        const createdEdges: ActionEdge[] = [];
        if (data.dependsOn && data.dependsOn.length > 0) {
          for (const depId of data.dependsOn) {
            const edge: ActionEdge = {
              id: generateId("ae"),
              type: "requires",
              sourceActionId: action.id,
              targetActionId: depId,
              createdAt: now,
            };
            await kv.set(KV.actionEdges, edge.id, edge);
            await safeAudit(kv, "sketch_create", "mem::sketch-add", [edge.id], {
              action: "add.edge",
              sketchId: sketch.id,
            });
            createdEdges.push(edge);
          }
        }

        sketch.actionIds.push(action.id);
        await kv.set(KV.sketches, sketch.id, sketch);
        await safeAudit(kv, "sketch_create", "mem::sketch-add", [sketch.id], {
          action: "add.sketch-update",
          addedActionId: action.id,
        });

        return { success: true, action, edges: createdEdges };
      });
    },
  );

  sdk.registerFunction("mem::sketch-promote", 
    async (data: { sketchId: string; project?: string }) => {
      if (!data.sketchId) {
        return { success: false, error: "sketchId is required" };
      }

      return withKeyedLock(`mem:sketch:${data.sketchId}`, async () => {
        const sketch = await kv.get<Sketch>(KV.sketches, data.sketchId);
        if (!sketch) {
          return { success: false, error: "sketch not found" };
        }
        if (sketch.status !== "active") {
          return { success: false, error: "sketch is not active" };
        }

        const promotedIds: string[] = [];
        for (const actionId of sketch.actionIds) {
          const action = await kv.get<Action>(KV.actions, actionId);
          if (action) {
            delete action.sketchId;
            if (data.project) {
              action.project = data.project;
            }
            action.updatedAt = new Date().toISOString();
            await kv.set(KV.actions, action.id, action);
            await safeAudit(kv, "sketch_promote", "mem::sketch-promote", [action.id], {
              action: "promote.action",
              sketchId: sketch.id,
            });
            promotedIds.push(action.id);
          }
        }

        sketch.status = "promoted";
        sketch.promotedAt = new Date().toISOString();
        await kv.set(KV.sketches, sketch.id, sketch);
        await safeAudit(kv, "sketch_promote", "mem::sketch-promote", [sketch.id], {
          action: "promote.sketch",
          promotedIds,
        });

        return { success: true, promotedIds };
      });
    },
  );

  sdk.registerFunction("mem::sketch-discard", 
    async (data: { sketchId: string }) => {
      if (!data.sketchId) {
        return { success: false, error: "sketchId is required" };
      }

      return withKeyedLock(`mem:sketch:${data.sketchId}`, async () => {
        const sketch = await kv.get<Sketch>(KV.sketches, data.sketchId);
        if (!sketch) {
          return { success: false, error: "sketch not found" };
        }
        if (sketch.status !== "active") {
          return { success: false, error: "sketch is not active" };
        }

        const actionIdSet = new Set(sketch.actionIds);

        const allEdges = await kv.list<ActionEdge>(KV.actionEdges);
        for (const edge of allEdges) {
          if (
            actionIdSet.has(edge.sourceActionId) ||
            actionIdSet.has(edge.targetActionId)
          ) {
            await kv.delete(KV.actionEdges, edge.id);
            await safeAudit(kv, "sketch_discard", "mem::sketch-discard", [edge.id], {
              action: "discard.edge",
              sketchId: sketch.id,
            });
          }
        }

        for (const actionId of sketch.actionIds) {
          await kv.delete(KV.actions, actionId);
          await safeAudit(kv, "sketch_discard", "mem::sketch-discard", [actionId], {
            action: "discard.action",
            sketchId: sketch.id,
          });
        }

        sketch.status = "discarded";
        sketch.discardedAt = new Date().toISOString();
        await kv.set(KV.sketches, sketch.id, sketch);
        await safeAudit(kv, "sketch_discard", "mem::sketch-discard", [sketch.id], {
          action: "discard.sketch",
        });

        return { success: true, discardedCount: sketch.actionIds.length };
      });
    },
  );

  sdk.registerFunction("mem::sketch-list", 
    async (data: { status?: string; project?: string }) => {
      let sketches = await kv.list<Sketch>(KV.sketches);

      if (data.status) {
        sketches = sketches.filter((s) => s.status === data.status);
      }
      if (data.project) {
        sketches = sketches.filter((s) => s.project === data.project);
      }

      sketches.sort(
        (a, b) =>
          new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
      );

      const results = sketches.map((s) => ({
        ...s,
        actionCount: s.actionIds.length,
      }));

      return { success: true, sketches: results };
    },
  );

  sdk.registerFunction("mem::sketch-gc", 
    async () => {
      const sketches = await kv.list<Sketch>(KV.sketches);
      const now = Date.now();
      let collected = 0;

      for (const sketch of sketches) {
        if (
          sketch.status !== "active" ||
          new Date(sketch.expiresAt).getTime() > now
        ) {
          continue;
        }

        await withKeyedLock(`mem:sketch:${sketch.id}`, async () => {
          const current = await kv.get<Sketch>(KV.sketches, sketch.id);
          if (
            !current ||
            current.status !== "active" ||
            new Date(current.expiresAt).getTime() > now
          ) {
            return;
          }

          const actionIdSet = new Set(current.actionIds);

          const allEdges = await kv.list<ActionEdge>(KV.actionEdges);
          for (const edge of allEdges) {
            if (
              actionIdSet.has(edge.sourceActionId) ||
              actionIdSet.has(edge.targetActionId)
            ) {
              await kv.delete(KV.actionEdges, edge.id);
              await safeAudit(kv, "sketch_discard", "mem::sketch-gc", [edge.id], {
                action: "gc.edge",
                sketchId: current.id,
              });
            }
          }

          for (const actionId of current.actionIds) {
            await kv.delete(KV.actions, actionId);
            await safeAudit(kv, "sketch_discard", "mem::sketch-gc", [actionId], {
              action: "gc.action",
              sketchId: current.id,
            });
          }

          current.status = "discarded";
          current.discardedAt = new Date().toISOString();
          await kv.set(KV.sketches, current.id, current);
          await safeAudit(kv, "sketch_discard", "mem::sketch-gc", [current.id], {
            action: "gc.sketch",
          });
          collected++;
        });
      }

      return { success: true, collected };
    },
  );
}