Skip to content

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

10.0 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, Routine, RoutineStep, RoutineRun } from "../types.js";
import { recordAudit } from "./audit.js";

export function registerRoutinesFunction(sdk: IIIClient, kv: StateKV): void {
  sdk.registerFunction("mem::routine-create", 
    async (data: {
      name: string;
      description?: string;
      steps: RoutineStep[];
      tags?: string[];
      frozen?: boolean;
      sourceProceduralIds?: string[];
    }) => {
      if (!data.name || !Array.isArray(data.steps) || data.steps.length === 0) {
        return { success: false, error: "name and steps are required" };
      }

      for (let i = 0; i < data.steps.length; i++) {
        if (!data.steps[i].title?.trim()) {
          return { success: false, error: `step ${i} must have a title` };
        }
      }

      const orders = data.steps.map((s, i) => s.order ?? i);
      const uniqueOrders = new Set(orders);
      if (uniqueOrders.size !== orders.length) {
        return { success: false, error: "duplicate step orders" };
      }
      for (const step of data.steps) {
        if (step.dependsOn) {
          for (const dep of step.dependsOn) {
            if (!uniqueOrders.has(dep)) {
              return { success: false, error: `step ${step.order ?? data.steps.indexOf(step)} depends on unknown order ${dep}` };
            }
          }
        }
      }

      const now = new Date().toISOString();
      const routine: Routine = {
        id: generateId("rtn"),
        name: data.name.trim(),
        description: (data.description || "").trim(),
        steps: data.steps.map((s, i) => ({
          order: s.order ?? i,
          title: s.title,
          description: s.description || "",
          actionTemplate: s.actionTemplate || {},
          dependsOn: s.dependsOn || [],
        })),
        createdAt: now,
        updatedAt: now,
        frozen: data.frozen ?? true,
        tags: data.tags || [],
        sourceProceduralIds: data.sourceProceduralIds || [],
      };

      await kv.set(KV.routines, routine.id, routine);
      await recordAudit(kv, "routine_run", "mem::routine-create", [routine.id], {
        action: "routine.create",
        stepCount: routine.steps.length,
      });
      return { success: true, routine };
    },
  );

  sdk.registerFunction("mem::routine-list", 
    async (data: { frozen?: boolean; tags?: string[] }) => {
      let routines = await kv.list<Routine>(KV.routines);
      if (data.frozen !== undefined) {
        routines = routines.filter((r) => r.frozen === data.frozen);
      }
      if (data.tags && data.tags.length > 0) {
        routines = routines.filter((r) =>
          data.tags!.some((t) => r.tags.includes(t)),
        );
      }
      routines.sort(
        (a, b) =>
          new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime(),
      );
      return { success: true, routines };
    },
  );

  sdk.registerFunction("mem::routine-run", 
    async (data: {
      routineId: string;
      initiatedBy?: string;
      project?: string;
      overrides?: Record<number, Partial<Action>>;
    }) => {
      if (!data.routineId) {
        return { success: false, error: "routineId is required" };
      }

      return withKeyedLock(`mem:routine:${data.routineId}`, async () => {
        const routine = await kv.get<Routine>(KV.routines, data.routineId);
        if (!routine) {
          return { success: false, error: "routine not found" };
        }

        const now = new Date().toISOString();
        const stepOrderToActionId = new Map<number, string>();
        const actionIds: string[] = [];
        const stepStatus: Record<number, "pending" | "active" | "done" | "failed"> = {};

        for (const step of routine.steps) {
          const template = step.actionTemplate || {};
          const override = data.overrides?.[step.order] || {};

          const hasDeps = (step.dependsOn || []).length > 0;
          const action: Action = {
            id: generateId("act"),
            title: override.title || template.title || step.title,
            description:
              override.description ||
              template.description ||
              step.description,
            status: hasDeps ? "blocked" : "pending",
            priority:
              override.priority ?? template.priority ?? 5,
            createdAt: now,
            updatedAt: now,
            createdBy: data.initiatedBy || "routine",
            project: data.project || template.project,
            tags: [
              ...(template.tags || []),
              ...(override.tags || []),
              `routine:${routine.id}`,
            ],
            sourceObservationIds: [],
            sourceMemoryIds: [],
            metadata: { routineId: routine.id, stepOrder: step.order },
          };

          await kv.set(KV.actions, action.id, action);
          stepOrderToActionId.set(step.order, action.id);
          actionIds.push(action.id);
          stepStatus[step.order] = "pending";
        }

        for (const step of routine.steps) {
          const actionId = stepOrderToActionId.get(step.order);
          if (!actionId) continue;

          for (const depOrder of step.dependsOn) {
            const depActionId = stepOrderToActionId.get(depOrder);
            if (!depActionId) continue;
            const edge = {
              id: generateId("ae"),
              type: "requires" as const,
              sourceActionId: actionId,
              targetActionId: depActionId,
              createdAt: now,
            };
            await kv.set(KV.actionEdges, edge.id, edge);
          }
        }

        const run: RoutineRun = {
          id: generateId("run"),
          routineId: routine.id,
          status: "running",
          startedAt: now,
          actionIds,
          stepStatus,
          initiatedBy: data.initiatedBy || "unknown",
        };

        await kv.set(KV.routineRuns, run.id, run);
        await recordAudit(kv, "routine_run", "mem::routine-run", [run.id], {
          action: "routine.run",
          routineId: routine.id,
          actionIds,
          initiatedBy: data.initiatedBy || "unknown",
        });

        return {
          success: true,
          run,
          actionsCreated: actionIds.length,
        };
      });
    },
  );

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

      const run = await kv.get<RoutineRun>(KV.routineRuns, data.runId);
      if (!run) {
        return { success: false, error: "run not found" };
      }

      const actionStates: Array<{
        actionId: string;
        status: string;
        title: string;
      }> = [];
      let allDone = true;
      let anyFailed = false;

      let statusChanged = false;
      for (const actionId of run.actionIds) {
        const action = await kv.get<Action>(KV.actions, actionId);
        if (action) {
          actionStates.push({
            actionId: action.id,
            status: action.status,
            title: action.title,
          });
          if (action.status !== "done") allDone = false;
          if (action.status === "cancelled") anyFailed = true;

          const stepOrder = (action.metadata as { stepOrder?: number })?.stepOrder;
          if (stepOrder !== undefined && stepOrder in run.stepStatus) {
            let mapped: "pending" | "active" | "done" | "failed";
            if (action.status === "cancelled") {
              mapped = "failed";
            } else if (action.status === "blocked") {
              mapped = "pending";
            } else {
              mapped = action.status as "pending" | "active" | "done";
            }
            if (run.stepStatus[stepOrder] !== mapped) {
              run.stepStatus[stepOrder] = mapped;
              statusChanged = true;
            }
          }
        } else {
          actionStates.push({
            actionId,
            status: "cancelled",
            title: "(missing)",
          });
          allDone = false;
          anyFailed = true;
        }
      }

      if (allDone && run.status === "running") {
        run.status = "completed";
        run.completedAt = new Date().toISOString();
        statusChanged = true;
      } else if (anyFailed && run.status === "running") {
        run.status = "failed";
        statusChanged = true;
      }

      if (statusChanged) {
        await kv.set(KV.routineRuns, run.id, run);
        await recordAudit(kv, "routine_run", "mem::routine-status", [run.id], {
          action: "routine.status",
          status: run.status,
        });
      }

      return {
        success: true,
        run,
        actions: actionStates,
        progress: {
          total: run.actionIds.length,
          done: actionStates.filter((a) => a.status === "done").length,
          active: actionStates.filter((a) => a.status === "active").length,
          pending: actionStates.filter((a) => a.status === "pending").length,
          blocked: actionStates.filter((a) => a.status === "blocked").length,
          cancelled: actionStates.filter((a) => a.status === "cancelled").length,
        },
      };
    },
  );

  sdk.registerFunction("mem::routine-freeze", 
    async (data: { routineId: string }) => {
      if (!data.routineId) {
        return { success: false, error: "routineId is required" };
      }
      return withKeyedLock(`mem:routine:${data.routineId}`, async () => {
        const routine = await kv.get<Routine>(KV.routines, data.routineId);
        if (!routine) {
          return { success: false, error: "routine not found" };
        }
        routine.frozen = true;
        routine.updatedAt = new Date().toISOString();
        await kv.set(KV.routines, routine.id, routine);
        await recordAudit(kv, "routine_run", "mem::routine-freeze", [routine.id], {
          action: "routine.freeze",
          frozen: true,
        });
        return { success: true, routine };
      });
    },
  );
}