Skip to content

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

8.8 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, Lease } from "../types.js";
import { recordAudit } from "./audit.js";

const DEFAULT_LEASE_TTL_MS = 10 * 60 * 1000;
const MAX_LEASE_TTL_MS = 60 * 60 * 1000;

export function registerLeasesFunction(sdk: IIIClient, kv: StateKV): void {
  sdk.registerFunction("mem::lease-acquire", 
    async (data: { actionId: string; agentId: string; ttlMs?: number }) => {
      if (!data.actionId || !data.agentId) {
        return { success: false, error: "actionId and agentId are required" };
      }

      const rawTtl = typeof data.ttlMs === "number" && Number.isFinite(data.ttlMs) && data.ttlMs > 0
        ? data.ttlMs
        : DEFAULT_LEASE_TTL_MS;
      const ttl = Math.min(rawTtl, MAX_LEASE_TTL_MS);

      return withKeyedLock(`mem:action:${data.actionId}`, async () => {
        const action = await kv.get<Action>(KV.actions, data.actionId);
        if (!action) {
          return { success: false, error: "action not found" };
        }
        if (action.status === "done" || action.status === "cancelled") {
          return { success: false, error: "action already completed" };
        }
        if (action.status === "blocked") {
          return { success: false, error: "action is blocked" };
        }

        const existingLeases = await kv.list<Lease>(KV.leases);
        const activeLease = existingLeases.find(
          (l) =>
            l.actionId === data.actionId &&
            l.status === "active" &&
            new Date(l.expiresAt).getTime() > Date.now(),
        );

        if (activeLease) {
          if (activeLease.agentId === data.agentId) {
            return {
              success: true,
              lease: activeLease,
              renewed: false,
              message: "Already holding this lease",
            };
          }
          return {
            success: false,
            error: "action already leased",
            heldBy: activeLease.agentId,
            expiresAt: activeLease.expiresAt,
          };
        }

        const now = new Date();
        const lease: Lease = {
          id: generateId("lse"),
          actionId: data.actionId,
          agentId: data.agentId,
          acquiredAt: now.toISOString(),
          expiresAt: new Date(now.getTime() + ttl).toISOString(),
          status: "active",
        };

        await kv.set(KV.leases, lease.id, lease);
        await recordAudit(kv, "lease_acquire", "mem::lease-acquire", [lease.id], {
          actionId: data.actionId,
          agentId: data.agentId,
          expiresAt: lease.expiresAt,
        });

        const before = { ...action };
        action.status = "active";
        action.assignedTo = data.agentId;
        action.updatedAt = now.toISOString();
        await kv.set(KV.actions, action.id, action);
        await recordAudit(kv, "action_update", "mem::lease-acquire", [action.id], {
          before,
          after: action,
        });

        return { success: true, lease, renewed: false };
      });
    },
  );

  sdk.registerFunction("mem::lease-release", 
    async (data: { actionId: string; agentId: string; result?: string }) => {
      if (!data.actionId || !data.agentId) {
        return { success: false, error: "actionId and agentId are required" };
      }

      return withKeyedLock(`mem:action:${data.actionId}`, async () => {
        const leases = await kv.list<Lease>(KV.leases);
        const activeLease = leases.find(
          (l) =>
            l.actionId === data.actionId &&
            l.agentId === data.agentId &&
            l.status === "active" &&
            new Date(l.expiresAt).getTime() > Date.now(),
        );

        if (!activeLease) {
          return { success: false, error: "no active lease found for this agent" };
        }

        activeLease.status = "released";
        await kv.set(KV.leases, activeLease.id, activeLease);
        await recordAudit(kv, "lease_release", "mem::lease-release", [activeLease.id], {
          actionId: data.actionId,
          agentId: data.agentId,
          status: "released",
        });

        const action = await kv.get<Action>(KV.actions, data.actionId);
        if (action && action.status === "active" && action.assignedTo === data.agentId) {
          const before = { ...action };
          if (data.result) {
            action.status = "done";
            action.result = data.result;
          } else {
            action.status = "pending";
          }
          action.assignedTo = undefined;
          action.updatedAt = new Date().toISOString();
          await kv.set(KV.actions, action.id, action);
          await recordAudit(kv, "action_update", "mem::lease-release", [action.id], {
            before,
            after: action,
            agentId: data.agentId,
          });
        }

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

  sdk.registerFunction("mem::lease-renew", 
    async (data: { actionId: string; agentId: string; ttlMs?: number }) => {
      if (!data.actionId || !data.agentId) {
        return { success: false, error: "actionId and agentId are required" };
      }

      const rawTtl = typeof data.ttlMs === "number" && Number.isFinite(data.ttlMs) && data.ttlMs > 0
        ? data.ttlMs
        : DEFAULT_LEASE_TTL_MS;
      const ttl = Math.min(rawTtl, MAX_LEASE_TTL_MS);

      return withKeyedLock(`mem:action:${data.actionId}`, async () => {
        const leases = await kv.list<Lease>(KV.leases);
        const activeLease = leases.find(
          (l) =>
            l.actionId === data.actionId &&
            l.agentId === data.agentId &&
            l.status === "active" &&
            new Date(l.expiresAt).getTime() > Date.now(),
        );

        if (!activeLease) {
          return { success: false, error: "no active (non-expired) lease to renew" };
        }

        const now = new Date();
        const base = Math.max(now.getTime(), new Date(activeLease.expiresAt).getTime());
        const beforeLease = { ...activeLease };
        activeLease.expiresAt = new Date(base + ttl).toISOString();
        activeLease.renewedAt = now.toISOString();
        await kv.set(KV.leases, activeLease.id, activeLease);
        await recordAudit(kv, "lease_renew", "mem::lease-renew", [activeLease.id], {
          actionId: data.actionId,
          agentId: data.agentId,
          before: beforeLease,
          after: activeLease,
        });

        return { success: true, lease: activeLease };
      });
    },
  );

  sdk.registerFunction("mem::lease-cleanup", 
    async () => {
      const leases = await kv.list<Lease>(KV.leases);
      const now = Date.now();
      let expired = 0;

      for (const lease of leases) {
        if (
          lease.status === "active" &&
          new Date(lease.expiresAt).getTime() <= now
        ) {
          const didExpire = await withKeyedLock(
            `mem:action:${lease.actionId}`,
            async () => {
              const currentLease = await kv.get<Lease>(KV.leases, lease.id);
              if (
                !currentLease ||
                currentLease.status !== "active" ||
                new Date(currentLease.expiresAt).getTime() > Date.now()
              ) {
                return false;
              }
              currentLease.status = "expired";
              await kv.set(KV.leases, currentLease.id, currentLease);
              await recordAudit(kv, "lease_release", "mem::lease-cleanup", [currentLease.id], {
                action: "expire",
                actionId: currentLease.actionId,
                agentId: currentLease.agentId,
              });

              const action = await kv.get<Action>(KV.actions, currentLease.actionId);
              const otherActiveLease = (await kv.list<Lease>(KV.leases)).some(
                (l) =>
                  l.id !== currentLease.id &&
                  l.actionId === currentLease.actionId &&
                  l.status === "active" &&
                  new Date(l.expiresAt).getTime() > Date.now(),
              );
              if (
                action &&
                !otherActiveLease &&
                action.status === "active" &&
                action.assignedTo === currentLease.agentId
              ) {
                action.status = "pending";
                action.assignedTo = undefined;
                action.updatedAt = new Date().toISOString();
                await kv.set(KV.actions, action.id, action);
                await recordAudit(kv, "action_update", "mem::lease-cleanup", [action.id], {
                  action: "status-change",
                  newStatus: action.status,
                  actionId: action.id,
                });
              }
              return true;
            },
          );
          if (didExpire) expired++;
        }
      }

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