Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

19.1 KB
Raw Blame
import * as Schema from "effect/Schema";
import * as Predicate from "effect/Predicate";

import * as NodeCrypto from "node:crypto";
import {
  AKERU_MEMORY_APPROVAL_REQUESTED_ACTIVITY,
  AKERU_MEMORY_APPROVAL_RESOLVED_ACTIVITY,
  AkeruMemoryCandidateId,
  AkeruMemoryId,
  AkeruMemoryRootId,
  AKERU_MEMORY_FACT_MAX_CHARS,
  BotId,
  CommandId,
  EventId,
  ThreadId,
  type AkeruMemoryApprovalRequest,
  type AkeruMemoryDecisionReceipt,
  type AkeruMemoryRevision,
  AkeruMemoryTargetScope,
  type AkeruMemoryThreadAccess,
} from "@akeru/contracts";
import * as Context from "effect/Context";
import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Semaphore from "effect/Semaphore";
import * as SqlClient from "effect/unstable/sql/SqlClient";
import { BotInboxService } from "../bot-inbox/service.ts";
import { ServerConfig } from "../config.ts";
import { OrchestrationEngineService } from "../orchestration/Services/OrchestrationEngine.ts";
import { ProjectionSnapshotQuery } from "../orchestration/Services/ProjectionSnapshotQuery.ts";
import { assertSafeContent } from "./BotMemory.ts";
import { resolveAuthorizedMemoryPartitions } from "./EntityMemoryAccess.ts";
import { EntityMemoryRepository } from "./Services/EntityMemoryRepository.ts";
import {
  MemoryApprovalError,
  type MemoryApprovalsShape,
  memoryApprovalIncidentKey,
  SCOPE_LABELS,
  boundedSummary,
} from "./MemoryShareProposal.ts";
import {
  encodeAffectedBotIds,
  CandidateRow,
  decodeCandidateRow,
  decodeReceiptRow,
  failWith,
} from "./MemoryApprovalRows.ts";

export class MemoryApprovals extends Context.Service<MemoryApprovals, MemoryApprovalsShape>()(
  "akeru-bot/memory/MemoryApprovals",
) {}

const decodeTargetScope = Schema.decodeUnknownSync(AkeruMemoryTargetScope);

const make = Effect.gen(function* () {
  const sql = yield* SqlClient.SqlClient;
  const repository = yield* EntityMemoryRepository;
  const orchestrationEngine = yield* OrchestrationEngineService;
  const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
  const config = yield* ServerConfig;
  const botInbox = BotInboxService.forSecretsDir(config.secretsDir);
  const decideLock = yield* Semaphore.make(1);
  const nowIso = DateTime.now.pipe(Effect.map(DateTime.formatIso));

  const affectedBotsFor = (access: AkeruMemoryThreadAccess) => {
    const authorBotId = access.respondingBotId ?? access.botId;

    return access.groupId === null
      ? authorBotId === null
        ? []
        : [authorBotId]
      : [...access.groupMemberBotIds];
  };

  const appendActivity = (input: {
    readonly threadId: ThreadId;
    readonly candidateId: string;
    readonly phase: "requested" | "resolved";
    readonly summary: string;
    readonly payload: AkeruMemoryApprovalRequest | AkeruMemoryDecisionReceipt;
    readonly createdAt: string;
  }) =>
    orchestrationEngine
      .dispatch({
        type: "thread.activity.append",
        commandId: CommandId.make(`memory-approval:${input.candidateId}:${input.phase}`),
        threadId: input.threadId,
        activity: {
          // ProjectionSnapshotQuery pins pending requests by this exact ID.
          id: EventId.make(`memory-approval:${input.candidateId}:${input.phase}`),
          tone: input.phase === "requested" ? "approval" : "info",
          kind:
            input.phase === "requested"
              ? AKERU_MEMORY_APPROVAL_REQUESTED_ACTIVITY
              : AKERU_MEMORY_APPROVAL_RESOLVED_ACTIVITY,
          summary: input.summary,
          payload: input.payload,
          turnId: null,
          createdAt: input.createdAt,
        },
        createdAt: input.createdAt,
      })
      .pipe(Effect.mapError(failWith("Could not record the memory approval")));

  const openInboxItem = Effect.fn("MemoryApprovals.openInboxItem")(function* (
    request: AkeruMemoryApprovalRequest,
  ) {
    const thread = yield* projectionSnapshotQuery
      .getThreadShellById(request.sourceThreadId)
      .pipe(Effect.orElseSucceed(() => Option.none()));

    const botId =
      request.authorBotId ??
      Option.match(thread, {
        onNone: () => null,
        onSome: (value) => value.respondingBotId ?? value.botId ?? null,
      });

    if (botId === null) return;

    const snapshot = yield* projectionSnapshotQuery
      .getShellSnapshot()
      .pipe(Effect.orElseSucceed(() => null));

    const bot = snapshot?.bots.find((candidate) => candidate.id === botId);

    if (!bot) return;
    yield* Effect.sync(() =>
      botInbox.ensureOpen({
        incidentKey: memoryApprovalIncidentKey(request.candidateId),
        kind: "approval-request",
        botId,
        botName: bot.name,
        taskOrRoutine: Option.match(thread, {
          onNone: () => "Memory",
          onSome: (value) => value.title,
        }),
        lastFailure: boundedSummary(
          `Save to ${SCOPE_LABELS[request.scope]} memory: ${request.fact}`,
        ),
        nextAction: "Approve or reject this memory.",
        memoryApproval: request,
      }),
    );
  });

  const propose: MemoryApprovalsShape["propose"] = Effect.fn("MemoryApprovals.propose")(
    function* (input) {
      if (input.fact.length > AKERU_MEMORY_FACT_MAX_CHARS) {
        return yield* new MemoryApprovalError({ message: "Memory text is too long." });
      }

      const createdAt = yield* nowIso;

      if (input.mode === "auto" && !input.sensitive) {
        const memoryId = AkeruMemoryId.make(NodeCrypto.randomUUID());

        const revision = yield* repository
          .insertScopedFact({
            access: input.access,
            scope: input.scope,
            fact: input.fact,
            sensitive: false,
            confidence: 1,
            sourceMessageId: null,
            memoryId,
            createdAt,
          })
          .pipe(Effect.mapError(failWith("Could not save the memory")));

        return { status: "saved", memoryId: revision.rootId } as const;
      }

      // Check the scope before storing, so no card appears that can never be approved.
      const partitions = yield* resolveAuthorizedMemoryPartitions(input.access).pipe(
        Effect.mapError(failWith("Could not store the memory candidate")),
      );

      if (!partitions.some((partition) => partition.scope === input.scope)) {
        return yield* new MemoryApprovalError({
          message: `The ${input.scope} memory scope is not available to this chat.`,
        });
      }

      const candidateId = AkeruMemoryCandidateId.make(NodeCrypto.randomUUID());
      const authorBotId = input.access.respondingBotId ?? input.access.botId;

      const request: AkeruMemoryApprovalRequest = {
        candidateId,
        fact: input.fact,
        scope: input.scope,
        sensitive: input.sensitive,
        sourceThreadId: input.access.threadId,
        authorBotId,
        affectedBotIds: affectedBotsFor(input.access),
      };

      const affectedBotIdsJson = yield* encodeAffectedBotIds(request.affectedBotIds).pipe(
        Effect.mapError(failWith("Could not store the memory candidate")),
      );

      yield* sql`
        INSERT INTO akeru_memory_candidates (
          candidate_id, tenant_id, initiating_user_id, source_thread_id,
          source_message_id, author_bot_id, fact_text, target_scope, sensitive,
          confidence, affected_bot_ids_json, status, created_at
        ) VALUES (
          ${candidateId}, ${input.access.tenantId}, ${input.access.userId},
          ${input.access.threadId}, ${null}, ${authorBotId}, ${input.fact},
          ${input.scope}, ${input.sensitive ? 1 : 0}, ${1},
          ${affectedBotIdsJson}, 'pending', ${createdAt}
        )
      `.pipe(Effect.mapError(failWith("Could not store the memory candidate")));
      // Without its chat card the candidate cannot be decided, so drop it
      // when the request cannot be published.
      yield* appendActivity({
        threadId: input.access.threadId,
        candidateId,
        phase: "requested",
        summary: `Save to ${SCOPE_LABELS[input.scope]} memory?`,
        payload: request,
        createdAt,
      }).pipe(
        Effect.tapError(() =>
          sql`
            DELETE FROM akeru_memory_candidates
            WHERE tenant_id = ${input.access.tenantId} AND candidate_id = ${candidateId}
          `.pipe(Effect.ignore),
        ),
      );
      yield* openInboxItem(request);

      return { status: "pending", candidateId } as const;
    },
  );

  const readReceipt = (tenantId: string, candidateId: string) =>
    sql`
      SELECT status, fact_text AS fact, target_scope AS scope,
        affected_bot_ids_json AS affectedBotIds, memory_root_id AS memoryRootId,
        created_at AS createdAt
      FROM akeru_memory_decision_receipts
      WHERE tenant_id = ${tenantId} AND candidate_id = ${candidateId}
    `.pipe(
      Effect.flatMap((rows) =>
        rows.length === 0
          ? Effect.succeed(null)
          : decodeReceiptRow(rows[0]).pipe(
              Effect.map(
                (row): AkeruMemoryDecisionReceipt => ({
                  candidateId: AkeruMemoryCandidateId.make(candidateId),
                  status: row.status === "approved" ? "approved" : "rejected",
                  fact: row.fact,
                  scope: decodeTargetScope(row.scope),
                  affectedBotIds: row.affectedBotIds,
                  memoryRootId:
                    row.memoryRootId === null ? null : AkeruMemoryRootId.make(row.memoryRootId),
                  createdAt: row.createdAt,
                }),
              ),
            ),
      ),
      Effect.mapError(failWith("Could not read the memory decision")),
    );

  const reconcileResolved = Effect.fn("MemoryApprovals.reconcileResolved")(function* (
    candidate: typeof CandidateRow.Type,
    receipt: AkeruMemoryDecisionReceipt,
  ) {
    yield* appendActivity({
      threadId: ThreadId.make(candidate.sourceThreadId),
      candidateId: candidate.candidateId,
      phase: "resolved",
      summary:
        receipt.status === "approved"
          ? `Saved to ${SCOPE_LABELS[receipt.scope] ?? receipt.scope} memory`
          : "Memory not saved",
      payload: receipt,
      createdAt: receipt.createdAt,
    });
    yield* Effect.sync(() => botInbox.resolve(memoryApprovalIncidentKey(candidate.candidateId)));
  });

  const decide: MemoryApprovalsShape["decide"] = (input) =>
    decideLock
      .withPermit(
        Effect.gen(function* () {
          const { decision } = input;
          let access = input.access;

          const rows = yield* sql`
          SELECT candidate_id AS candidateId, tenant_id AS tenantId,
            source_thread_id AS sourceThreadId, source_message_id AS sourceMessageId,
            author_bot_id AS authorBotId, fact_text AS fact, target_scope AS scope,
            sensitive, confidence, affected_bot_ids_json AS affectedBotIds, status
          FROM akeru_memory_candidates
          WHERE tenant_id = ${access.tenantId} AND candidate_id = ${decision.candidateId}
        `.pipe(
            Effect.flatMap(Effect.forEach((row) => decodeCandidateRow(row))),
            Effect.mapError(failWith("Could not read the memory candidate")),
          );

          const candidate = rows[0];

          if (candidate === undefined || candidate.sourceThreadId !== access.threadId) {
            return yield* new MemoryApprovalError({
              message: "This memory approval does not belong to this chat.",
            });
          }

          if (candidate.status !== "pending") {
            const existing = yield* readReceipt(access.tenantId, candidate.candidateId);

            if (existing !== null) {
              yield* reconcileResolved(candidate, existing);

              return existing;
            }

            return yield* new MemoryApprovalError({
              message: "This memory approval was already decided.",
            });
          }

          // Save under the bot that asked, even if a different group bot is
          // responding by the time the user decides. A bot that has since left
          // the group falls back to the current responder so the decision lands.
          const authorBotId = candidate.authorBotId;

          if (
            authorBotId !== null &&
            (access.groupId === null ||
              access.groupMemberBotIds.some((memberBotId) => memberBotId === authorBotId))
          ) {
            access = { ...access, respondingBotId: BotId.make(authorBotId) };
          }

          const createdAt = yield* nowIso;

          let fact =
            decision.decision === "approve" ? (decision.fact ?? candidate.fact) : candidate.fact;

          if (fact.length > AKERU_MEMORY_FACT_MAX_CHARS) {
            return yield* new MemoryApprovalError({ message: "Memory text is too long." });
          }

          if (decision.decision === "approve" && decision.fact !== undefined) {
            // An edited fact goes through the same guard as a tool-proposed one.
            yield* Effect.try({
              try: () => assertSafeContent(fact),
              catch: (cause) =>
                new MemoryApprovalError({
                  message: cause instanceof Error ? cause.message : "Memory content was rejected.",
                }),
            });
          }

          if (
            decision.decision === "approve" &&
            decision.scope !== undefined &&
            decision.scope !== candidate.scope
          ) {
            return yield* new MemoryApprovalError({
              message: "The approval scope must match the candidate scope.",
            });
          }

          let scope =
            decision.decision === "approve"
              ? (decision.scope ?? decodeTargetScope(candidate.scope))
              : decodeTargetScope(candidate.scope);

          let approvedRevision: AkeruMemoryRevision | null = null;

          if (decision.decision === "approve") {
            approvedRevision = yield* repository
              .insertScopedFact({
                access,
                scope,
                fact,
                sensitive: candidate.sensitive === 1,
                confidence: candidate.confidence,
                sourceMessageId: null,
                memoryId: AkeruMemoryId.make(`approval:${candidate.candidateId}`),
                createdAt,
              })
              .pipe(
                Effect.catchTag("EntityMemoryConflictError", () =>
                  repository
                    .getCurrent({
                      access,
                      rootId: AkeruMemoryRootId.make(`approval:${candidate.candidateId}`),
                    })
                    .pipe(
                      Effect.flatMap((existing) =>
                        existing.fact === fact &&
                        existing.partition.scope === scope &&
                        existing.approvalState === "approved" &&
                        existing.deletionState === "active"
                          ? Effect.succeed(existing)
                          : Effect.fail(
                              new MemoryApprovalError({
                                message:
                                  "This memory approval already has a different approved fact or scope.",
                              }),
                            ),
                      ),
                    ),
                ),
                Effect.mapError((cause) =>
                  Predicate.isTagged(cause, "MemoryApprovalError")
                    ? cause
                    : failWith("Could not save the memory")(cause),
                ),
              );
            // A conflict may mean the insert committed before the receipt write.
            // Use the durable revision as the source of truth for the receipt.
            fact = approvedRevision.fact;
            scope = decodeTargetScope(approvedRevision.partition.scope);
          } else {
            const orphan = yield* repository
              .getCurrent({
                access,
                rootId: AkeruMemoryRootId.make(`approval:${candidate.candidateId}`),
              })
              .pipe(Effect.catchTag("EntityMemoryNotFoundError", () => Effect.succeed(null)));

            // A retry after a crash may find the orphan already retracted.
            if (orphan !== null && orphan.deletionState === "active") {
              yield* repository
                .applyMutation({
                  access,
                  mutation: {
                    operation: "fact.forget",
                    memoryId: orphan.rootId,
                    expectedRevision: orphan.revision,
                  },
                  memoryId: AkeruMemoryId.make(`approval:${candidate.candidateId}:rejected`),
                  updatedAt: createdAt,
                  sharedProjectApproval: "approved",
                })
                .pipe(Effect.mapError(failWith("Could not retract the rejected memory")));
            }
          }

          const memoryRootId = approvedRevision?.rootId ?? null;

          const receipt: AkeruMemoryDecisionReceipt = {
            candidateId: AkeruMemoryCandidateId.make(candidate.candidateId),
            status: decision.decision === "approve" ? "approved" : "rejected",
            fact,
            scope,
            affectedBotIds: candidate.affectedBotIds,
            memoryRootId,
            createdAt,
          };

          const affectedBotIdsJson = yield* encodeAffectedBotIds(receipt.affectedBotIds).pipe(
            Effect.mapError(failWith("Could not record the memory decision")),
          );

          yield* sql
            .withTransaction(
              Effect.gen(function* () {
                yield* sql`
                UPDATE akeru_memory_candidates
                SET status = ${receipt.status}, decided_at = ${createdAt},
                  decided_memory_root_id = ${memoryRootId}
                WHERE tenant_id = ${access.tenantId} AND candidate_id = ${candidate.candidateId}
              `;
                yield* sql`
                INSERT INTO akeru_memory_decision_receipts (
                  receipt_id, candidate_id, tenant_id, status, fact_text, target_scope,
                  affected_bot_ids_json, memory_root_id, created_at
                ) VALUES (
                  ${NodeCrypto.randomUUID()}, ${candidate.candidateId}, ${access.tenantId},
                  ${receipt.status}, ${fact}, ${scope}, ${affectedBotIdsJson},
                  ${memoryRootId}, ${createdAt}
                )
              `;
              }),
            )
            .pipe(Effect.mapError(failWith("Could not record the memory decision")));
          yield* reconcileResolved(candidate, receipt);

          return receipt;
        }),
      )
      .pipe(
        Effect.mapError((cause) =>
          Predicate.isTagged(cause, "MemoryApprovalError")
            ? cause
            : failWith("Could not record the memory decision")(cause),
        ),
      );

  return { propose, decide } satisfies MemoryApprovalsShape;
});

export const MemoryApprovalsLive = Layer.effect(MemoryApprovals, make);

export { MemoryApprovalError } from "./MemoryShareProposal.ts";

export type { MemoryShareProposal } from "./MemoryShareProposal.ts";

export type { MemoryShareResult } from "./MemoryShareProposal.ts";

export type { MemoryApprovalsShape } from "./MemoryShareProposal.ts";

export { memoryApprovalIncidentKey } from "./MemoryShareProposal.ts";