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.
feat(contracts): define Akeru memory and usage records (#22)
Leoaadd9bcd2409
diff --git a/packages/contracts/src/akeruMemory.test.ts b/packages/contracts/src/akeruMemory.test.tsnew file mode 100644index 000000000..22cf75f50--- /dev/null+++ b/packages/contracts/src/akeruMemory.test.ts@@ -0,0 +1,180 @@+import { assert, describe, it } from "@effect/vitest";+import * as Effect from "effect/Effect";+import * as Schema from "effect/Schema";++import {+ AKERU_MEMORY_PACKET_MAX_CHARS,+ AKERU_MEMORY_PACKET_MAX_ESTIMATED_TOKENS,+ AKERU_MEMORY_PACKET_MAX_FACTS,+ AkeruMemoryCandidate,+ AkeruMemoryCandidateDecision,+ AkeruMemoryDecisionReceipt,+ AkeruMemoryPacket,+ AkeruMemoryMutateInput,+ AkeruMemoryRevision,+} from "./akeruMemory.ts";++const revision = {+ id: "memory-1",+ rootId: "root-1",+ revision: 1,+ partition: { tenantId: "tenant-1", scope: "bot-user", partitionId: "bot-1:user-1" },+ entityKind: "user",+ entityId: "user-1",+ kind: "preference",+ value: { theme: "dark" },+ fact: "The user prefers dark themes.",+ sourceThreadId: "thread-1",+ sourceMessageId: "message-1",+ authorBotId: "bot-1",+ initiatingUserId: "user-1",+ createdAt: "2026-08-30T21:00:00.000Z",+ confirmedAt: "2026-08-30T21:00:00.000Z",+ updatedAt: "2026-08-30T21:00:00.000Z",+ confidence: 0.9,+ approvalState: "approved",+ supersedesId: null,+ supersededById: null,+ visibility: "private",+ deletionState: "active",+ pinned: false,+ sensitive: false,+ affectedBotIds: ["bot-1"],+} as const;++describe("Akeru memory contracts", () => {+ it.effect("decodes a complete immutable memory revision", () =>+ Effect.gen(function* () {+ const decoded = yield* Schema.decodeUnknownEffect(AkeruMemoryRevision)(revision);+ assert.equal(decoded.partition.scope, "bot-user");+ assert.equal(decoded.value.theme, "dark");+ }),+ );++ it.effect("rejects confidence outside the supported range", () =>+ Effect.gen(function* () {+ const exit = yield* Schema.decodeUnknownEffect(AkeruMemoryRevision)({+ ...revision,+ confidence: 1.01,+ }).pipe(Effect.exit);+ assert.isTrue(exit._tag === "Failure");+ }),+ );++ it.effect("types pending candidates and editable approval decisions", () =>+ Effect.gen(function* () {+ const candidate = yield* Schema.decodeUnknownEffect(AkeruMemoryCandidate)({+ candidateId: "candidate-1",+ tenantId: "tenant-1",+ initiatingUserId: "user-1",+ sourceThreadId: "thread-1",+ sourceMessageId: "message-1",+ authorBotId: "bot-1",+ fact: "The project uses Bun.",+ scope: "project",+ sensitive: false,+ confidence: 0.9,+ affectedBotIds: ["bot-1", "bot-2"],+ status: "pending",+ createdAt: "2026-08-30T21:00:00.000Z",+ decidedAt: null,+ decidedMemoryRootId: null,+ });+ const decision = yield* Schema.decodeUnknownEffect(AkeruMemoryCandidateDecision)({+ candidateId: candidate.candidateId,+ decision: "approve",+ fact: "The project uses Bun 2.",+ scope: "workspace",+ });++ assert.equal(candidate.status, "pending");+ assert.equal(decision.decision, "approve");+ }),+ );++ it.effect("requires rejected decisions and durable receipts to identify the candidate", () =>+ Effect.gen(function* () {+ const rejected = yield* Schema.decodeUnknownEffect(AkeruMemoryCandidateDecision)({+ candidateId: "candidate-1",+ decision: "reject",+ });+ const receipt = yield* Schema.decodeUnknownEffect(AkeruMemoryDecisionReceipt)({+ candidateId: "candidate-1",+ status: "rejected",+ fact: "Do not save this.",+ scope: "private",+ affectedBotIds: ["bot-1"],+ memoryRootId: null,+ createdAt: "2026-08-30T21:00:00.000Z",+ });++ assert.equal(rejected.decision, "reject");+ assert.isNull(receipt.memoryRootId);+ }),+ );++ it.effect("enforces all provider memory packet bounds", () =>+ Effect.gen(function* () {+ const fact = {+ memoryId: "memory-1",+ expectedRevision: 1,+ scope: "user",+ kind: "fact",+ fact: "A fact",+ pinned: false,+ confidence: 1,+ updatedAt: "2026-08-30T21:00:00.000Z",+ } as const;+ const decode = Schema.decodeUnknownEffect(AkeruMemoryPacket);+ const tooManyFacts = yield* decode({+ threadId: "thread-1",+ facts: Array.from({ length: AKERU_MEMORY_PACKET_MAX_FACTS + 1 }, () => fact),+ estimatedTokens: 1,+ rendered: "memory",+ }).pipe(Effect.exit);+ const tooManyTokens = yield* decode({+ threadId: "thread-1",+ facts: [fact],+ estimatedTokens: AKERU_MEMORY_PACKET_MAX_ESTIMATED_TOKENS + 1,+ rendered: "memory",+ }).pipe(Effect.exit);+ const tooManyChars = yield* decode({+ threadId: "thread-1",+ facts: [fact],+ estimatedTokens: 1,+ rendered: "x".repeat(AKERU_MEMORY_PACKET_MAX_CHARS + 1),+ }).pipe(Effect.exit);++ assert.isTrue(tooManyFacts._tag === "Failure");+ assert.isTrue(tooManyTokens._tag === "Failure");+ assert.isTrue(tooManyChars._tag === "Failure");+ }),+ );++ it.effect("decodes allowlisted memory mutations and rejects extra fields", () =>+ Effect.gen(function* () {+ const decode = Schema.decodeUnknownEffect(AkeruMemoryMutateInput);+ const edit = yield* decode({+ threadId: "thread-1",+ mutation: {+ operation: "fact.edit",+ memoryId: "root-1",+ expectedRevision: 1,+ fact: "The user prefers concise replies.",+ },+ });+ const arbitrary = yield* decode({+ threadId: "thread-1",+ mutation: { operation: "database.execute", sql: "DELETE FROM memory" },+ }).pipe(Effect.exit);+ const deleteWithoutRevision = yield* decode({+ threadId: "thread-1",+ mutation: { operation: "fact.delete", memoryId: "root-1" },+ }).pipe(Effect.exit);++ assert.equal(edit.mutation.operation, "fact.edit");+ assert.isTrue(arbitrary._tag === "Failure");+ assert.isTrue(deleteWithoutRevision._tag === "Failure");+ }),+ );+});diff --git a/packages/contracts/src/akeruMemory.ts b/packages/contracts/src/akeruMemory.tsnew file mode 100644index 000000000..d1f6934bc--- /dev/null+++ b/packages/contracts/src/akeruMemory.ts@@ -0,0 +1,411 @@+import * as Schema from "effect/Schema";+import * as Effect from "effect/Effect";++import {+ BotId,+ GroupId,+ IsoDateTime,+ MessageId,+ NonNegativeInt,+ PositiveInt,+ ProjectId,+ ThreadId,+ TrimmedNonEmptyString,+} from "./baseSchemas.ts";++export const AKERU_MEMORY_PACKET_MAX_FACTS = 24;+export const AKERU_MEMORY_PACKET_MAX_CHARS = 12_000;+export const AKERU_MEMORY_PACKET_MAX_ESTIMATED_TOKENS = 3_000;++export const AkeruMemoryId = TrimmedNonEmptyString.pipe(Schema.brand("AkeruMemoryId"));+export type AkeruMemoryId = typeof AkeruMemoryId.Type;++export const AkeruMemoryRootId = TrimmedNonEmptyString.pipe(Schema.brand("AkeruMemoryRootId"));+export type AkeruMemoryRootId = typeof AkeruMemoryRootId.Type;++export const AkeruMemoryCandidateId = TrimmedNonEmptyString.pipe(+ Schema.brand("AkeruMemoryCandidateId"),+);+export type AkeruMemoryCandidateId = typeof AkeruMemoryCandidateId.Type;++export const AkeruMemoryTenantId = TrimmedNonEmptyString.pipe(Schema.brand("AkeruMemoryTenantId"));+export type AkeruMemoryTenantId = typeof AkeruMemoryTenantId.Type;++export const AkeruMemoryUserId = TrimmedNonEmptyString.pipe(Schema.brand("AkeruMemoryUserId"));+export type AkeruMemoryUserId = typeof AkeruMemoryUserId.Type;++export const AkeruMemoryEntityId = TrimmedNonEmptyString.pipe(Schema.brand("AkeruMemoryEntityId"));+export type AkeruMemoryEntityId = typeof AkeruMemoryEntityId.Type;++export const AkeruMemoryPartitionId = TrimmedNonEmptyString.pipe(+ Schema.brand("AkeruMemoryPartitionId"),+);+export type AkeruMemoryPartitionId = typeof AkeruMemoryPartitionId.Type;++export const AkeruMemoryScope = Schema.Literals([+ "user",+ "bot-user",+ "bot",+ "project",+ "group",+ "workspace",+ "thread",+]);+export type AkeruMemoryScope = typeof AkeruMemoryScope.Type;++export const AkeruMemoryVisibility = Schema.Literals(["private", "shared"]);+export type AkeruMemoryVisibility = typeof AkeruMemoryVisibility.Type;++export const AkeruMemoryApprovalState = Schema.Literals(["pending", "approved", "rejected"]);+export type AkeruMemoryApprovalState = typeof AkeruMemoryApprovalState.Type;++export const AkeruMemoryCandidateStatus = Schema.Literals(["pending", "approved", "rejected"]);+export type AkeruMemoryCandidateStatus = typeof AkeruMemoryCandidateStatus.Type;++export const AkeruMemoryTargetScope = Schema.Literals([+ "private",+ "bot",+ "project",+ "group",+ "workspace",+]);+export type AkeruMemoryTargetScope = typeof AkeruMemoryTargetScope.Type;++export const AkeruMemoryDeletionState = Schema.Literals(["active", "tombstoned", "deleted"]);+export type AkeruMemoryDeletionState = typeof AkeruMemoryDeletionState.Type;++export const AkeruMemoryKind = Schema.Literals([+ "fact",+ "preference",+ "identity",+ "relationship",+ "routine",+ "instruction",+]);+export type AkeruMemoryKind = typeof AkeruMemoryKind.Type;++export const AkeruMemoryEntityKind = Schema.Literals([+ "user",+ "bot",+ "person",+ "project",+ "group",+ "workspace",+ "other",+]);+export type AkeruMemoryEntityKind = typeof AkeruMemoryEntityKind.Type;++export const AkeruMemoryConfidence = Schema.Number.check(+ Schema.isBetween({ minimum: 0, maximum: 1 }),+);+export type AkeruMemoryConfidence = typeof AkeruMemoryConfidence.Type;++export const AkeruMemoryPartition = Schema.Struct({+ tenantId: AkeruMemoryTenantId,+ scope: AkeruMemoryScope,+ partitionId: AkeruMemoryPartitionId,+});+export type AkeruMemoryPartition = typeof AkeruMemoryPartition.Type;++export const AkeruMemoryRevision = Schema.Struct({+ id: AkeruMemoryId,+ rootId: AkeruMemoryRootId,+ revision: PositiveInt,+ partition: AkeruMemoryPartition,+ entityKind: AkeruMemoryEntityKind,+ entityId: AkeruMemoryEntityId,+ kind: AkeruMemoryKind,+ value: Schema.Record(Schema.String, Schema.Unknown),+ fact: TrimmedNonEmptyString,+ sourceThreadId: Schema.NullOr(ThreadId),+ sourceMessageId: Schema.NullOr(MessageId),+ authorBotId: Schema.NullOr(BotId),+ initiatingUserId: AkeruMemoryUserId,+ createdAt: IsoDateTime,+ confirmedAt: Schema.NullOr(IsoDateTime),+ updatedAt: IsoDateTime,+ confidence: AkeruMemoryConfidence,+ approvalState: AkeruMemoryApprovalState,+ supersedesId: Schema.NullOr(AkeruMemoryId),+ supersededById: Schema.NullOr(AkeruMemoryId),+ visibility: AkeruMemoryVisibility,+ deletionState: AkeruMemoryDeletionState,+ pinned: Schema.Boolean,+ sensitive: Schema.Boolean,+ affectedBotIds: Schema.Array(BotId),+});+export type AkeruMemoryRevision = typeof AkeruMemoryRevision.Type;++export const AkeruMemoryCandidate = Schema.Struct({+ candidateId: AkeruMemoryCandidateId,+ tenantId: AkeruMemoryTenantId,+ initiatingUserId: AkeruMemoryUserId,+ sourceThreadId: ThreadId,+ sourceMessageId: Schema.NullOr(MessageId),+ authorBotId: Schema.NullOr(BotId),+ fact: TrimmedNonEmptyString,+ scope: AkeruMemoryTargetScope,+ sensitive: Schema.Boolean,+ confidence: AkeruMemoryConfidence,+ affectedBotIds: Schema.Array(BotId),+ status: AkeruMemoryCandidateStatus,+ createdAt: IsoDateTime,+ decidedAt: Schema.NullOr(IsoDateTime),+ decidedMemoryRootId: Schema.NullOr(AkeruMemoryRootId),+});+export type AkeruMemoryCandidate = typeof AkeruMemoryCandidate.Type;++export const AkeruMemoryCandidateDecision = Schema.Union([+ Schema.Struct({+ candidateId: AkeruMemoryCandidateId,+ decision: Schema.Literal("approve"),+ fact: Schema.optional(TrimmedNonEmptyString),+ scope: Schema.optional(AkeruMemoryTargetScope),+ }),+ Schema.Struct({+ candidateId: AkeruMemoryCandidateId,+ decision: Schema.Literal("reject"),+ }),+]);+export type AkeruMemoryCandidateDecision = typeof AkeruMemoryCandidateDecision.Type;++export const AkeruMemoryDecisionReceipt = Schema.Struct({+ candidateId: AkeruMemoryCandidateId,+ status: Schema.Literals(["approved", "rejected"]),+ fact: TrimmedNonEmptyString,+ scope: AkeruMemoryTargetScope,+ affectedBotIds: Schema.Array(BotId),+ memoryRootId: Schema.NullOr(AkeruMemoryRootId),+ createdAt: IsoDateTime,+});+export type AkeruMemoryDecisionReceipt = typeof AkeruMemoryDecisionReceipt.Type;++export const AkeruMemoryArchiveFile = Schema.Struct({+ path: TrimmedNonEmptyString,+ mediaType: Schema.Literal("text/markdown"),+ sha256: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),+ content: Schema.String,+});+export type AkeruMemoryArchiveFile = typeof AkeruMemoryArchiveFile.Type;++export const AkeruMemoryArchiveV1 = Schema.Struct({+ schemaVersion: Schema.Literal(1),+ threadId: ThreadId,+ complete: Schema.Boolean,+ createdAt: IsoDateTime,+ files: Schema.Array(AkeruMemoryArchiveFile),+ manifestSha256: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),+});+export type AkeruMemoryArchiveV1 = typeof AkeruMemoryArchiveV1.Type;++export const AkeruMemoryArchiveTarget = Schema.Literals(["thread", "bot", "project", "all"]);+export type AkeruMemoryArchiveTarget = typeof AkeruMemoryArchiveTarget.Type;++export const AkeruMemoryArchiveRevision = Schema.Struct({+ revision: AkeruMemoryRevision,+ sha256: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),+});+export type AkeruMemoryArchiveRevision = typeof AkeruMemoryArchiveRevision.Type;++export const AkeruMemoryInspectInput = Schema.Struct({ threadId: ThreadId });+export type AkeruMemoryInspectInput = typeof AkeruMemoryInspectInput.Type;++export const AkeruConversationMemoryRecord = Schema.Struct({+ id: TrimmedNonEmptyString,+ generationCount: NonNegativeInt,+ originType: Schema.Literals(["initial", "reflection"]),+ activeObservations: Schema.String,+ bufferedObservations: Schema.String,+ bufferedReflection: Schema.NullOr(Schema.String),+ totalTokensObserved: NonNegativeInt,+ observationTokenCount: NonNegativeInt,+ createdAt: IsoDateTime,+ updatedAt: IsoDateTime,+});+export type AkeruConversationMemoryRecord = typeof AkeruConversationMemoryRecord.Type;++export const AkeruConversationMemorySnapshot = Schema.Struct({+ current: Schema.NullOr(AkeruConversationMemoryRecord),+ history: Schema.Array(AkeruConversationMemoryRecord),+});+export type AkeruConversationMemorySnapshot = typeof AkeruConversationMemorySnapshot.Type;++export const AkeruMemoryArchiveConversation = Schema.Struct({+ threadId: ThreadId,+ snapshot: AkeruConversationMemorySnapshot,+ sha256: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),+});+export type AkeruMemoryArchiveConversation = typeof AkeruMemoryArchiveConversation.Type;++export const AkeruMemoryArchiveV2 = Schema.Struct({+ schemaVersion: Schema.Literal(2),+ anchorThreadId: ThreadId,+ target: AkeruMemoryArchiveTarget,+ complete: Schema.Boolean,+ createdAt: IsoDateTime,+ files: Schema.Array(AkeruMemoryArchiveFile),+ revisions: Schema.Array(AkeruMemoryArchiveRevision),+ conversations: Schema.Array(AkeruMemoryArchiveConversation),+ manifestSha256: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),+});+export type AkeruMemoryArchiveV2 = typeof AkeruMemoryArchiveV2.Type;++export const AkeruMemoryArchive = Schema.Union([AkeruMemoryArchiveV1, AkeruMemoryArchiveV2]);+export type AkeruMemoryArchive = typeof AkeruMemoryArchive.Type;++export const AkeruMemorySnapshot = Schema.Struct({+ threadId: ThreadId,+ durable: Schema.Array(AkeruMemoryRevision),+ histories: Schema.Array(+ Schema.Struct({+ rootId: AkeruMemoryRootId,+ revisions: Schema.Array(AkeruMemoryRevision),+ }),+ ),+ pending: Schema.Array(AkeruMemoryCandidate),+ conversation: AkeruConversationMemorySnapshot,+});+export type AkeruMemorySnapshot = typeof AkeruMemorySnapshot.Type;++export const AkeruMemoryExportInput = Schema.Struct({+ threadId: ThreadId,+ complete: Schema.Boolean,+ target: AkeruMemoryArchiveTarget.pipe(+ Schema.withDecodingDefault(Effect.succeed("thread" as const)),+ ),+});+export type AkeruMemoryExportInput = typeof AkeruMemoryExportInput.Type;++export const AkeruMemoryImportClassification = Schema.Literals([+ "new",+ "changed",+ "conflicting",+ "skipped",+]);+export type AkeruMemoryImportClassification = typeof AkeruMemoryImportClassification.Type;++export const AkeruMemoryImportPreviewItem = Schema.Struct({+ rootId: AkeruMemoryRootId,+ classification: AkeruMemoryImportClassification,+ reason: TrimmedNonEmptyString,+});+export type AkeruMemoryImportPreviewItem = typeof AkeruMemoryImportPreviewItem.Type;++export const AkeruMemoryImportPreviewInput = Schema.Struct({+ threadId: ThreadId,+ target: AkeruMemoryArchiveTarget,+ archive: AkeruMemoryArchiveV2,+});+export type AkeruMemoryImportPreviewInput = typeof AkeruMemoryImportPreviewInput.Type;++export const AkeruMemoryImportPreview = Schema.Struct({+ previewHash: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),+ items: Schema.Array(AkeruMemoryImportPreviewItem),+});+export type AkeruMemoryImportPreview = typeof AkeruMemoryImportPreview.Type;++export const AkeruMemoryImportApplyInput = Schema.Struct({+ ...AkeruMemoryImportPreviewInput.fields,+ previewHash: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),+});+export type AkeruMemoryImportApplyInput = typeof AkeruMemoryImportApplyInput.Type;++export const AkeruMemoryImportApplyResult = Schema.Struct({+ imported: NonNegativeInt,+ changed: NonNegativeInt,+ skipped: NonNegativeInt,+});+export type AkeruMemoryImportApplyResult = typeof AkeruMemoryImportApplyResult.Type;++export const AkeruMemoryMutation = Schema.Union([+ Schema.Struct({+ operation: Schema.Literal("candidate.decide"),+ decision: AkeruMemoryCandidateDecision,+ }),+ Schema.Struct({+ operation: Schema.Literal("fact.edit"),+ memoryId: AkeruMemoryRootId,+ expectedRevision: PositiveInt,+ fact: TrimmedNonEmptyString,+ }),+ Schema.Struct({+ operation: Schema.Literal("fact.pin"),+ memoryId: AkeruMemoryRootId,+ expectedRevision: PositiveInt,+ pinned: Schema.Boolean,+ }),+ Schema.Struct({+ operation: Schema.Literal("fact.scope"),+ memoryId: AkeruMemoryRootId,+ expectedRevision: PositiveInt,+ scope: AkeruMemoryTargetScope,+ }),+ Schema.Struct({+ operation: Schema.Literal("fact.forget"),+ memoryId: AkeruMemoryRootId,+ expectedRevision: PositiveInt,+ }),+ Schema.Struct({+ operation: Schema.Literal("fact.delete"),+ memoryId: AkeruMemoryRootId,+ expectedRevision: PositiveInt,+ }),+ Schema.Struct({ operation: Schema.Literal("conversation.clear") }),+]);+export type AkeruMemoryMutation = typeof AkeruMemoryMutation.Type;++export const AkeruMemoryMutateInput = Schema.Struct({+ threadId: ThreadId,+ mutation: AkeruMemoryMutation,+});+export type AkeruMemoryMutateInput = typeof AkeruMemoryMutateInput.Type;++export const AkeruMemoryMutationResult = Schema.Union([+ Schema.Struct({ kind: Schema.Literal("candidate"), receipt: AkeruMemoryDecisionReceipt }),+ Schema.Struct({ kind: Schema.Literal("revision"), revision: AkeruMemoryRevision }),+ Schema.Struct({ kind: Schema.Literal("deleted"), memoryId: AkeruMemoryRootId }),+ Schema.Struct({ kind: Schema.Literal("conversation-cleared") }),+]);+export type AkeruMemoryMutationResult = typeof AkeruMemoryMutationResult.Type;++export class AkeruMemoryOperationError extends Schema.TaggedErrorClass<AkeruMemoryOperationError>()(+ "AkeruMemoryOperationError",+ { operation: TrimmedNonEmptyString, detail: TrimmedNonEmptyString },+) {}++export const AkeruMemoryPacketFact = Schema.Struct({+ memoryId: AkeruMemoryRootId,+ expectedRevision: PositiveInt,+ scope: AkeruMemoryScope,+ kind: AkeruMemoryKind,+ fact: TrimmedNonEmptyString,+ pinned: Schema.Boolean,+ confidence: AkeruMemoryConfidence,+ updatedAt: IsoDateTime,+});+export type AkeruMemoryPacketFact = typeof AkeruMemoryPacketFact.Type;++export const AkeruMemoryPacket = Schema.Struct({+ threadId: ThreadId,+ facts: Schema.Array(AkeruMemoryPacketFact).check(+ Schema.isMaxLength(AKERU_MEMORY_PACKET_MAX_FACTS),+ ),+ estimatedTokens: NonNegativeInt.check(+ Schema.isLessThanOrEqualTo(AKERU_MEMORY_PACKET_MAX_ESTIMATED_TOKENS),+ ),+ rendered: Schema.String.check(Schema.isMaxLength(AKERU_MEMORY_PACKET_MAX_CHARS)),+});+export type AkeruMemoryPacket = typeof AkeruMemoryPacket.Type;++export const AkeruMemoryThreadAccess = Schema.Struct({+ tenantId: AkeruMemoryTenantId,+ userId: AkeruMemoryUserId,+ threadId: ThreadId,+ projectId: ProjectId,+ workspaceRoot: TrimmedNonEmptyString,+ botId: Schema.NullOr(BotId),+ groupId: Schema.NullOr(GroupId),+ respondingBotId: Schema.NullOr(BotId),+ groupMemberBotIds: Schema.Array(BotId),+});+export type AkeruMemoryThreadAccess = typeof AkeruMemoryThreadAccess.Type;diff --git a/packages/contracts/src/akeruUsage.test.ts b/packages/contracts/src/akeruUsage.test.tsnew file mode 100644index 000000000..d9985840c--- /dev/null+++ b/packages/contracts/src/akeruUsage.test.ts@@ -0,0 +1,28 @@+import { assert, it } from "@effect/vitest";+import * as Effect from "effect/Effect";+import * as Schema from "effect/Schema";++import { AkeruBotUsageSnapshot } from "./akeruUsage.ts";++it.effect("decodes bot usage with unavailable provider totals", () =>+ Effect.gen(function* () {+ const snapshot = yield* Schema.decodeUnknownEffect(AkeruBotUsageSnapshot)({+ botId: "bot-1",+ consumedTokens: 12,+ reservedTokens: 32,+ measurements: {+ input: { tokens: 5, unavailableEntries: 0 },+ output: { tokens: 7, unavailableEntries: 0 },+ observer: { tokens: 0, unavailableEntries: 1 },+ reflector: { tokens: 0, unavailableEntries: 1 },+ },+ entries: [],+ usageCap: { unit: "tokens", limit: 1_000 },+ estimatedCost: { status: "unavailable", usd: null },+ subscriptionPool: { status: "unavailable", used: null, limit: null, unit: null },+ });++ assert.strictEqual(snapshot.usageCap?.limit, 1_000);+ assert.strictEqual(snapshot.estimatedCost.status, "unavailable");+ }),+);diff --git a/packages/contracts/src/akeruUsage.ts b/packages/contracts/src/akeruUsage.tsnew file mode 100644index 000000000..7f613bd2f--- /dev/null+++ b/packages/contracts/src/akeruUsage.ts@@ -0,0 +1,101 @@+import * as Schema from "effect/Schema";++import {+ BotId,+ IsoDateTime,+ NonNegativeInt,+ ThreadId,+ TrimmedNonEmptyString,+ TurnId,+} from "./baseSchemas.ts";+import { ProviderDriverKind } from "./providerInstance.ts";+import { BotUsageCap } from "./orchestration.ts";++export const AkeruUsageReservationId = TrimmedNonEmptyString.pipe(+ Schema.brand("AkeruUsageReservationId"),+);+export type AkeruUsageReservationId = typeof AkeruUsageReservationId.Type;++export const AkeruUsageCategory = Schema.Literals([+ "turn",+ "tool",+ "observer",+ "reflector",+ "extraction",+ "recall",+ "routine",+ "delegated",+]);+export type AkeruUsageCategory = typeof AkeruUsageCategory.Type;++export const AkeruUsageState = Schema.Literals(["reserved", "reported", "unavailable", "released"]);+export type AkeruUsageState = typeof AkeruUsageState.Type;++export const AkeruUsageEntry = Schema.Struct({+ reservationId: AkeruUsageReservationId,+ sourceKey: TrimmedNonEmptyString,+ botId: BotId,+ threadId: Schema.NullOr(ThreadId),+ turnId: Schema.NullOr(TurnId),+ category: AkeruUsageCategory,+ state: AkeruUsageState,+ reservedTokens: NonNegativeInt,+ inputTokens: Schema.NullOr(NonNegativeInt),+ outputTokens: Schema.NullOr(NonNegativeInt),+ reasoningTokens: Schema.NullOr(NonNegativeInt),+ provider: Schema.NullOr(ProviderDriverKind),+ model: Schema.NullOr(TrimmedNonEmptyString),+ unavailableReason: Schema.NullOr(TrimmedNonEmptyString),+ createdAt: IsoDateTime,+ settledAt: Schema.NullOr(IsoDateTime),+});+export type AkeruUsageEntry = typeof AkeruUsageEntry.Type;++export const AkeruBotUsageSummary = Schema.Struct({+ botId: BotId,+ consumedTokens: NonNegativeInt,+ reservedTokens: NonNegativeInt,+ measurements: Schema.Struct({+ input: Schema.Struct({ tokens: NonNegativeInt, unavailableEntries: NonNegativeInt }),+ output: Schema.Struct({ tokens: NonNegativeInt, unavailableEntries: NonNegativeInt }),+ observer: Schema.Struct({ tokens: NonNegativeInt, unavailableEntries: NonNegativeInt }),+ reflector: Schema.Struct({ tokens: NonNegativeInt, unavailableEntries: NonNegativeInt }),+ }),+ entries: Schema.Array(AkeruUsageEntry),+});+export type AkeruBotUsageSummary = typeof AkeruBotUsageSummary.Type;++export const AkeruBotUsageInput = Schema.Struct({ botId: BotId });+export type AkeruBotUsageInput = typeof AkeruBotUsageInput.Type;++export const AkeruBotUsageSnapshot = Schema.Struct({+ ...AkeruBotUsageSummary.fields,+ usageCap: Schema.NullOr(BotUsageCap),+ estimatedCost: Schema.Union([+ Schema.Struct({+ status: Schema.Literal("available"),+ usd: Schema.Number.check(Schema.isFinite(), Schema.isGreaterThanOrEqualTo(0)),+ }),+ Schema.Struct({ status: Schema.Literal("unavailable"), usd: Schema.Null }),+ ]),+ subscriptionPool: Schema.Union([+ Schema.Struct({+ status: Schema.Literal("available"),+ used: NonNegativeInt,+ limit: NonNegativeInt,+ unit: TrimmedNonEmptyString,+ }),+ Schema.Struct({+ status: Schema.Literal("unavailable"),+ used: Schema.Null,+ limit: Schema.Null,+ unit: Schema.Null,+ }),+ ]),+});+export type AkeruBotUsageSnapshot = typeof AkeruBotUsageSnapshot.Type;++export class AkeruBotUsageReadError extends Schema.TaggedErrorClass<AkeruBotUsageReadError>()(+ "AkeruBotUsageReadError",+ { botId: BotId, detail: TrimmedNonEmptyString },+) {}diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.tsindex 759b87fdf..bd9e7305d 100644--- a/packages/contracts/src/index.ts+++ b/packages/contracts/src/index.ts@@ -1,6 +1,8 @@export * from "./baseSchemas.ts";export * from "./background.ts";export * from "./productFeedback.ts";+export * from "./akeruMemory.ts";+export * from "./akeruUsage.ts";export * from "./auth.ts";export * from "./environment.ts";export * from "./environmentHttp.ts";