@yattalo/task-system 0.4.0 → 0.5.0

package/templates/uca/memory.ts

@@ -0,0 +1,326 @@
+import { mutation, query } from "../_generated/server";
+import { v } from "convex/values";
+
+const memoryTierValidator = v.union(v.literal("hot"), v.literal("warm"), v.literal("cold"));
+
+function makeId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function estimateTokens(text: string): number {
+  return Math.max(1, Math.ceil(text.trim().split(/\s+/).length * 1.3));
+}
+
+function tierToContextTier(tier: "hot" | "warm" | "cold"): "draft" | "reviewed" | "curated" {
+  if (tier === "hot") return "draft";
+  if (tier === "warm") return "reviewed";
+  return "curated";
+}
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length === 0 || b.length === 0 || a.length !== b.length) return 0;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    dot += a[i]! * b[i]!;
+    normA += a[i]! * a[i]!;
+    normB += b[i]! * b[i]!;
+  }
+  if (normA === 0 || normB === 0) return 0;
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+function lexicalScore(haystack: string, queryText: string): number {
+  if (!queryText) return 0;
+  const lowerHaystack = haystack.toLowerCase();
+  const lowerQuery = queryText.toLowerCase();
+  if (lowerHaystack.includes(lowerQuery)) return 1;
+
+  const tokens = lowerQuery.split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) return 0;
+  let matched = 0;
+  for (const token of tokens) {
+    if (lowerHaystack.includes(token)) matched += 1;
+  }
+  return matched / tokens.length;
+}
+
+export const listMemory = query({
+  args: {
+    agentId: v.optional(v.string()),
+    tier: v.optional(memoryTierValidator),
+    taskId: v.optional(v.string()),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    let items = await ctx.db.query("agentMemory").collect();
+    if (args.agentId) items = items.filter((item) => item.agentId === args.agentId);
+    if (args.tier) items = items.filter((item) => item.tier === args.tier);
+    if (args.taskId) items = items.filter((item) => item.taskId === args.taskId);
+    items.sort((a, b) => b.updatedAt - a.updatedAt);
+    return args.limit ? items.slice(0, args.limit) : items;
+  },
+});
+
+export const memoryStats = query({
+  args: { agentId: v.optional(v.string()) },
+  handler: async (ctx, { agentId }) => {
+    let items = await ctx.db.query("agentMemory").collect();
+    if (agentId) items = items.filter((item) => item.agentId === agentId);
+
+    const byTier: Record<string, { count: number; tokens: number }> = {
+      hot: { count: 0, tokens: 0 },
+      warm: { count: 0, tokens: 0 },
+      cold: { count: 0, tokens: 0 },
+    };
+
+    for (const item of items) {
+      byTier[item.tier].count += 1;
+      byTier[item.tier].tokens += item.tokens;
+    }
+
+    return {
+      total: items.length,
+      totalTokens: items.reduce((sum, item) => sum + item.tokens, 0),
+      byTier,
+    };
+  },
+});
+
+export const addMemory = mutation({
+  args: {
+    memoryId: v.optional(v.string()),
+    agentId: v.string(),
+    taskId: v.optional(v.string()),
+    tier: memoryTierValidator,
+    content: v.string(),
+    summary: v.optional(v.string()),
+    tokens: v.optional(v.number()),
+    embedding: v.optional(v.array(v.number())),
+    tags: v.optional(v.array(v.string())),
+    linkedContextEntryId: v.optional(v.string()),
+    expiresAt: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const memoryId = args.memoryId ?? makeId("mem");
+
+    const existing = await ctx.db
+      .query("agentMemory")
+      .withIndex("by_memoryId", (q: any) => q.eq("memoryId", memoryId))
+      .first();
+    if (existing) {
+      await ctx.db.patch(existing._id, {
+        agentId: args.agentId,
+        taskId: args.taskId,
+        tier: args.tier,
+        content: args.content,
+        summary: args.summary,
+        tokens: args.tokens ?? estimateTokens(args.content),
+        embedding: args.embedding,
+        tags: args.tags ?? existing.tags,
+        linkedContextEntryId: args.linkedContextEntryId,
+        expiresAt: args.expiresAt,
+        updatedAt: now,
+      });
+      return { memoryId, updated: true };
+    }
+
+    await ctx.db.insert("agentMemory", {
+      memoryId,
+      agentId: args.agentId,
+      taskId: args.taskId,
+      tier: args.tier,
+      content: args.content,
+      summary: args.summary,
+      tokens: args.tokens ?? estimateTokens(args.content),
+      embedding: args.embedding,
+      tags: args.tags ?? [],
+      linkedContextEntryId: args.linkedContextEntryId,
+      consolidatedFrom: undefined,
+      createdAt: now,
+      updatedAt: now,
+      expiresAt: args.expiresAt,
+    });
+
+    return { memoryId, created: true };
+  },
+});
+
+export const searchMemory = query({
+  args: {
+    agentId: v.optional(v.string()),
+    tier: v.optional(memoryTierValidator),
+    queryText: v.optional(v.string()),
+    tags: v.optional(v.array(v.string())),
+    queryEmbedding: v.optional(v.array(v.number())),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    let items = await ctx.db.query("agentMemory").collect();
+    if (args.agentId) items = items.filter((item) => item.agentId === args.agentId);
+    if (args.tier) items = items.filter((item) => item.tier === args.tier);
+    if (args.tags && args.tags.length > 0) {
+      const wanted = new Set(args.tags.map((tag) => tag.toLowerCase()));
+      items = items.filter((item) => item.tags.some((tag) => wanted.has(tag.toLowerCase())));
+    }
+
+    const scored = items.map((item) => {
+      const haystack = `${item.content}\n${item.summary ?? ""}\n${item.tags.join(" ")}`;
+      const lexical = args.queryText ? lexicalScore(haystack, args.queryText) : 0;
+      const vector =
+        args.queryEmbedding && Array.isArray(item.embedding)
+          ? cosineSimilarity(args.queryEmbedding, item.embedding)
+          : 0;
+      const recencyBoost = Math.max(0, 1 - (Date.now() - item.updatedAt) / (1000 * 60 * 60 * 24 * 30));
+      const score = lexical * 0.6 + vector * 0.3 + recencyBoost * 0.1;
+      return { item, score };
+    });
+
+    scored.sort((a, b) => b.score - a.score);
+    const limit = args.limit ?? 20;
+    return scored.slice(0, limit);
+  },
+});
+
+export const consolidateHotMemory = mutation({
+  args: {
+    agentId: v.string(),
+    maxTokens: v.optional(v.number()),
+    targetTier: v.optional(v.union(v.literal("warm"), v.literal("cold"))),
+  },
+  handler: async (ctx, { agentId, maxTokens, targetTier }) => {
+    const threshold = maxTokens ?? 40_000;
+    const target = targetTier ?? "warm";
+
+    const all = await ctx.db
+      .query("agentMemory")
+      .withIndex("by_agent_tier", (q: any) => q.eq("agentId", agentId).eq("tier", "hot"))
+      .collect();
+    const totalTokens = all.reduce((sum, item) => sum + item.tokens, 0);
+
+    if (totalTokens <= threshold || all.length === 0) {
+      return {
+        consolidated: false,
+        reason: "threshold_not_reached",
+        totalTokens,
+        threshold,
+      };
+    }
+
+    const ordered = [...all].sort((a, b) => a.updatedAt - b.updatedAt);
+    let rolling = 0;
+    const picked: any[] = [];
+    for (const item of ordered) {
+      picked.push(item);
+      rolling += item.tokens;
+      if (rolling >= threshold * 0.6) break;
+    }
+
+    const now = Date.now();
+    const consolidatedContent = picked
+      .map((item, index) => `(${index + 1}) ${item.summary ?? item.content}`)
+      .join("\n\n");
+
+    const consolidatedMemoryId = makeId("mem-consolidated");
+    await ctx.db.insert("agentMemory", {
+      memoryId: consolidatedMemoryId,
+      agentId,
+      taskId: undefined,
+      tier: target,
+      content: consolidatedContent,
+      summary: `Consolidated ${picked.length} hot memories`,
+      tokens: estimateTokens(consolidatedContent),
+      embedding: undefined,
+      tags: ["consolidated", "auto", target],
+      linkedContextEntryId: undefined,
+      consolidatedFrom: picked.map((item) => item.memoryId),
+      createdAt: now,
+      updatedAt: now,
+      expiresAt: undefined,
+    });
+
+    for (const item of picked) {
+      await ctx.db.patch(item._id, {
+        tier: "warm",
+        updatedAt: now,
+      });
+    }
+
+    const consolidationId = makeId("memc");
+    await ctx.db.insert("memoryConsolidations", {
+      consolidationId,
+      agentId,
+      sourceTier: "hot",
+      targetTier: target,
+      sourceMemoryIds: picked.map((item) => item.memoryId),
+      resultMemoryId: consolidatedMemoryId,
+      totalTokens: rolling,
+      createdAt: now,
+    });
+
+    return {
+      consolidated: true,
+      consolidationId,
+      sourceCount: picked.length,
+      sourceTokens: rolling,
+      resultMemoryId: consolidatedMemoryId,
+      targetTier: target,
+    };
+  },
+});
+
+export const syncMemoryToContext = mutation({
+  args: {
+    memoryId: v.string(),
+    projectId: v.optional(v.string()),
+    createdBy: v.optional(v.string()),
+  },
+  handler: async (ctx, { memoryId, projectId, createdBy }) => {
+    const memory = await ctx.db
+      .query("agentMemory")
+      .withIndex("by_memoryId", (q: any) => q.eq("memoryId", memoryId))
+      .first();
+    if (!memory) throw new Error(`Memory ${memoryId} not found`);
+
+    const now = Date.now();
+    const entryId = `ctx-${memory.memoryId}`;
+    const existing = await ctx.db
+      .query("contextEntries")
+      .filter((q: any) => q.eq(q.field("entryId"), entryId))
+      .first();
+
+    const base = {
+      projectId: projectId ?? "uca",
+      type: "learning",
+      content: memory.content,
+      summary: memory.summary,
+      tier: tierToContextTier(memory.tier),
+      promotionHistory: existing?.promotionHistory ?? [],
+      confidenceScore: memory.tier === "cold" ? 5 : memory.tier === "warm" ? 4 : 3,
+      validatedBy: existing?.validatedBy ?? [memory.agentId],
+      taskId: memory.taskId,
+      tags: [
+        ...new Set([...(memory.tags ?? []), "memory-sync", `tier:${memory.tier}`, `agent:${memory.agentId}`]),
+      ],
+      createdBy: createdBy ?? memory.agentId,
+      updatedAt: now,
+    };
+
+    if (existing) {
+      await ctx.db.patch(existing._id, base);
+      await ctx.db.patch(memory._id, { linkedContextEntryId: existing.entryId, updatedAt: now });
+      return { entryId: existing.entryId, updated: true };
+    }
+
+    await ctx.db.insert("contextEntries", {
+      entryId,
+      ...base,
+      createdAt: now,
+    });
+
+    await ctx.db.patch(memory._id, { linkedContextEntryId: entryId, updatedAt: now });
+    return { entryId, created: true };
+  },
+});

package/templates/uca/sessionBridge.ts

@@ -0,0 +1,238 @@
+import { internalMutation, mutation, query } from "../_generated/server";
+import { v } from "convex/values";
+
+const messageTypeValidator = v.union(
+  v.literal("handoff"),
+  v.literal("notification"),
+  v.literal("request"),
+  v.literal("response"),
+  v.literal("broadcast"),
+);
+
+const messageStatusValidator = v.union(
+  v.literal("pending"),
+  v.literal("delivered"),
+  v.literal("acknowledged"),
+  v.literal("expired"),
+);
+
+function makeId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+async function findMessage(ctx: any, messageId: string): Promise<any | null> {
+  return await ctx.db
+    .query("sessionBridgeMessages")
+    .withIndex("by_messageId", (q: any) => q.eq("messageId", messageId))
+    .first();
+}
+
+async function findTask(ctx: any, taskId: string): Promise<any | null> {
+  return await ctx.db
+    .query("tasks")
+    .withIndex("by_taskId", (q: any) => q.eq("taskId", taskId))
+    .first();
+}
+
+export const sendMessage = mutation({
+  args: {
+    messageId: v.optional(v.string()),
+    fromSessionId: v.string(),
+    toSessionId: v.optional(v.string()),
+    fromAgent: v.string(),
+    toAgent: v.optional(v.string()),
+    taskId: v.optional(v.string()),
+    messageType: messageTypeValidator,
+    content: v.string(),
+    summary: v.optional(v.string()),
+    expiresInMinutes: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const messageId = args.messageId ?? makeId("msg");
+
+    const existing = await findMessage(ctx, messageId);
+    if (existing) return { messageId, duplicated: true };
+
+    const expiresAt =
+      typeof args.expiresInMinutes === "number" && args.expiresInMinutes > 0
+        ? now + args.expiresInMinutes * 60_000
+        : undefined;
+
+    await ctx.db.insert("sessionBridgeMessages", {
+      messageId,
+      fromSessionId: args.fromSessionId,
+      toSessionId: args.toSessionId,
+      fromAgent: args.fromAgent,
+      toAgent: args.toAgent,
+      taskId: args.taskId,
+      messageType: args.messageType,
+      content: args.content,
+      summary: args.summary,
+      status: "pending",
+      createdAt: now,
+      deliveredAt: undefined,
+      acknowledgedAt: undefined,
+      expiresAt,
+    });
+
+    return { messageId, status: "pending", expiresAt };
+  },
+});
+
+export const inbox = query({
+  args: {
+    toSessionId: v.optional(v.string()),
+    toAgent: v.optional(v.string()),
+    status: v.optional(messageStatusValidator),
+    includeBroadcast: v.optional(v.boolean()),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const all = await ctx.db.query("sessionBridgeMessages").collect();
+    let messages = all.filter((message) => {
+      if (args.status && message.status !== args.status) return false;
+
+      const addressedToSession = args.toSessionId ? message.toSessionId === args.toSessionId : false;
+      const addressedToAgent = args.toAgent ? message.toAgent === args.toAgent : false;
+      const isBroadcast = message.messageType === "broadcast";
+
+      if (args.includeBroadcast ?? true) {
+        return addressedToSession || addressedToAgent || isBroadcast;
+      }
+      return addressedToSession || addressedToAgent;
+    });
+
+    messages.sort((a, b) => b.createdAt - a.createdAt);
+    return args.limit ? messages.slice(0, args.limit) : messages;
+  },
+});
+
+export const markDelivered = mutation({
+  args: {
+    messageId: v.string(),
+    deliveredBySessionId: v.optional(v.string()),
+  },
+  handler: async (ctx, { messageId }) => {
+    const message = await findMessage(ctx, messageId);
+    if (!message) throw new Error(`Message ${messageId} not found`);
+    if (message.status !== "pending") return { messageId, status: message.status };
+
+    await ctx.db.patch(message._id, {
+      status: "delivered",
+      deliveredAt: Date.now(),
+    });
+
+    return { messageId, status: "delivered" };
+  },
+});
+
+export const acknowledgeMessage = mutation({
+  args: {
+    messageId: v.string(),
+    acknowledgedBy: v.optional(v.string()),
+  },
+  handler: async (ctx, { messageId }) => {
+    const message = await findMessage(ctx, messageId);
+    if (!message) throw new Error(`Message ${messageId} not found`);
+
+    await ctx.db.patch(message._id, {
+      status: "acknowledged",
+      acknowledgedAt: Date.now(),
+      deliveredAt: message.deliveredAt ?? Date.now(),
+    });
+
+    return { messageId, status: "acknowledged" };
+  },
+});
+
+export const handoffTask = mutation({
+  args: {
+    fromSessionId: v.string(),
+    toSessionId: v.string(),
+    fromAgent: v.string(),
+    toAgent: v.string(),
+    taskId: v.string(),
+    summary: v.string(),
+    content: v.optional(v.string()),
+    contextRefs: v.optional(v.array(v.string())),
+  },
+  handler: async (ctx, args) => {
+    const task = await findTask(ctx, args.taskId);
+    if (!task) throw new Error(`Task ${args.taskId} not found`);
+
+    const messageId = makeId("handoff");
+    const now = Date.now();
+    const contextBlock = (args.contextRefs ?? []).length
+      ? `\n\nContext refs:\n- ${(args.contextRefs ?? []).join("\n- ")}`
+      : "";
+
+    await ctx.db.insert("sessionBridgeMessages", {
+      messageId,
+      fromSessionId: args.fromSessionId,
+      toSessionId: args.toSessionId,
+      fromAgent: args.fromAgent,
+      toAgent: args.toAgent,
+      taskId: args.taskId,
+      messageType: "handoff",
+      content: `${args.content ?? args.summary}${contextBlock}`,
+      summary: args.summary,
+      status: "pending",
+      createdAt: now,
+      deliveredAt: undefined,
+      acknowledgedAt: undefined,
+      expiresAt: undefined,
+    });
+
+    const history = Array.isArray(task.statusHistory) ? task.statusHistory : [];
+    await ctx.db.patch(task._id, {
+      agent: args.toAgent,
+      status: task.status === "done" ? "review" : "todo",
+      updatedAt: now,
+      statusHistory: [
+        ...history,
+        {
+          status: task.status === "done" ? "review" : "todo",
+          timestamp: now,
+          agent: args.fromAgent,
+          note: `Session handoff -> ${args.toAgent} (${args.toSessionId})`,
+        },
+      ],
+      notes: [task.notes ?? "", `\n\nHandoff summary (${new Date(now).toISOString()}):\n${args.summary}`].join(""),
+    });
+
+    return {
+      messageId,
+      taskId: args.taskId,
+      nextAgent: args.toAgent,
+      nextSessionId: args.toSessionId,
+    };
+  },
+});
+
+export const internalExpireMessages = internalMutation({
+  args: {},
+  handler: async (ctx) => {
+    const now = Date.now();
+    const all = await ctx.db.query("sessionBridgeMessages").collect();
+    const expired = all.filter(
+      (message) =>
+        typeof message.expiresAt === "number" &&
+        message.expiresAt <= now &&
+        message.status !== "acknowledged" &&
+        message.status !== "expired",
+    );
+
+    for (const message of expired) {
+      await ctx.db.patch(message._id, {
+        status: "expired",
+      });
+    }
+
+    return {
+      scanned: all.length,
+      expired: expired.length,
+      messageIds: expired.map((message) => message.messageId),
+    };
+  },
+});