dot-studio 0.0.1 → 0.0.2

package/dist/server/services/act-runtime/event-router.js

@@ -0,0 +1,102 @@
+/**
+ * event-router.ts — Subscription + relation-based event routing
+ *
+ * PRD §15.2: Routes events to participants based on:
+ * 1. Subscription + relation permission match
+ * 2. WakeCondition satisfaction
+ */
+import { Mailbox } from './mailbox.js';
+import { evaluateWakeCondition } from './wake-evaluator.js';
+import { payloadString } from './act-runtime-utils.js';
+// ── Subscription matching ───────────────────────────────
+function matchSubscription(participantKey, subscriptions, event) {
+    if (!subscriptions)
+        return false;
+    const payload = event.payload;
+    switch (event.type) {
+        case 'message.sent':
+        case 'message.delivered': {
+            const to = payloadString(payload, 'to');
+            if (to !== participantKey) {
+                return false;
+            }
+            const from = payloadString(payload, 'from');
+            const tag = payloadString(payload, 'tag');
+            const fromMatch = subscriptions.messagesFrom?.includes(from || '') ?? false;
+            const tagMatch = subscriptions.messageTags?.includes(tag || '') ?? false;
+            return fromMatch || tagMatch;
+        }
+        case 'board.posted':
+        case 'board.updated': {
+            const key = payloadString(payload, 'key');
+            if (!key)
+                return false;
+            return subscriptions.callboardKeys?.some((pattern) => {
+                if (pattern.endsWith('*')) {
+                    return key.startsWith(pattern.slice(0, -1));
+                }
+                return key === pattern;
+            }) ?? false;
+        }
+        case 'runtime.idle':
+            return subscriptions.eventTypes?.includes('runtime.idle') ?? false;
+        default:
+            return false;
+    }
+}
+// ── Relation permission check ───────────────────────────
+function hasRelationPermission(participantKey, event, relations) {
+    const source = event.source;
+    if (!source || source === participantKey)
+        return false;
+    // Check if there's a relation between source and this participant
+    return relations.some((rel) => {
+        const [a, b] = rel.between;
+        const pairMatch = (a === source && b === participantKey) || (a === participantKey && b === source);
+        if (!pairMatch)
+            return false;
+        // For one-way relations, only the second (target) can be woken by the first (source)
+        if (rel.direction === 'one-way') {
+            return a === source && b === participantKey;
+        }
+        return true;
+    });
+}
+// ── Main routing function ───────────────────────────────
+export function routeEvent(event, actDefinition, mailbox, recentEvents) {
+    const targets = [];
+    const seen = new Set();
+    // 1. Subscription + relation based wake-up
+    for (const [key, binding] of Object.entries(actDefinition.participants)) {
+        if (key === event.source)
+            continue; // Don't wake the source
+        const subMatch = matchSubscription(key, binding.subscriptions, event);
+        const relMatch = hasRelationPermission(key, event, actDefinition.relations);
+        // Direct message: always wake the recipient if relation allows it.
+        // 1:1 messages don't need explicit subscription — the `to` field is the routing key.
+        const isDirectMessageTarget = (event.type === 'message.sent' || event.type === 'message.delivered') &&
+            payloadString(event.payload, 'to') === key;
+        if ((subMatch && relMatch) || (isDirectMessageTarget && relMatch)) {
+            targets.push({
+                participantKey: key,
+                triggerEvent: event,
+                reason: 'subscription',
+            });
+            seen.add(key);
+        }
+    }
+    // 2. WakeCondition based wake-up
+    const triggeredConditions = mailbox.evaluateConditions(event, (cond, board, events) => evaluateWakeCondition(cond, board, events), recentEvents);
+    for (const cond of triggeredConditions) {
+        if (!seen.has(cond.createdBy)) {
+            targets.push({
+                participantKey: cond.createdBy,
+                triggerEvent: event,
+                wakeCondition: cond,
+                reason: 'wake-condition',
+            });
+            seen.add(cond.createdBy);
+        }
+    }
+    return targets;
+}

package/dist/server/services/act-runtime/mailbox.js

@@ -0,0 +1,149 @@
+/**
+ * mailbox.ts — Mailbox state management for Act Thread runtime
+ *
+ * PRD §6: Mailbox is the internal SoT for all Act collaboration state.
+ * - pending messages (in-memory, transient)
+ * - board (file-backed + memory cache, durable)
+ * - wake conditions (in-memory, transient)
+ */
+import { nanoid } from 'nanoid';
+// ── Mailbox ─────────────────────────────────────────────
+export class Mailbox {
+    // pending messages (in-memory, transient)
+    pendingMessages = [];
+    // board (file-backed + memory cache, durable)
+    board = new Map();
+    // wake conditions (in-memory, transient)
+    wakeConditions = [];
+    // ── Messages ────────────────────────────────────
+    addMessage(msg) {
+        const message = {
+            ...msg,
+            id: nanoid(),
+            timestamp: Date.now(),
+            status: 'pending',
+        };
+        this.pendingMessages.push(message);
+        return message;
+    }
+    getMessagesFor(participantKey) {
+        return this.pendingMessages.filter((m) => m.to === participantKey && m.status === 'pending');
+    }
+    getAllPendingMessages() {
+        return [...this.pendingMessages];
+    }
+    markDelivered(messageId) {
+        const idx = this.pendingMessages.findIndex((m) => m.id === messageId);
+        if (idx !== -1) {
+            // After delivery, message lives in performer's session — remove from mailbox
+            this.pendingMessages.splice(idx, 1);
+        }
+    }
+    // ── Board ───────────────────────────────────────
+    postToBoard(entry) {
+        const existing = this.board.get(entry.key);
+        // writePolicy enforcement
+        if (existing) {
+            const wp = existing.writePolicy || 'any';
+            if (wp === 'author-only' && existing.author !== entry.author) {
+                throw new Error(`Board key "${entry.key}" is author-only and owned by "${existing.author}".`);
+            }
+            // relation-peers could be checked here with relation context (future)
+        }
+        const boardEntry = {
+            ...entry,
+            id: existing?.id || nanoid(),
+            version: existing ? existing.version + 1 : 1,
+            timestamp: Date.now(),
+        };
+        if (existing && entry.updateMode === 'append') {
+            boardEntry.content = existing.content + '\n' + entry.content;
+        }
+        this.board.set(entry.key, boardEntry);
+        return boardEntry;
+    }
+    readBoard(key) {
+        return this.board.get(key);
+    }
+    getBoardSnapshot() {
+        return Array.from(this.board.values());
+    }
+    getBoardMap() {
+        return new Map(this.board);
+    }
+    // ── WakeCondition ───────────────────────────────
+    addWakeCondition(condition) {
+        const wc = {
+            ...condition,
+            id: nanoid(),
+            status: 'waiting',
+        };
+        this.wakeConditions.push(wc);
+        return wc;
+    }
+    getWakeConditions() {
+        return this.wakeConditions.filter((c) => c.status === 'waiting');
+    }
+    /**
+     * Evaluate all waiting conditions against an event.
+     * Returns conditions that were triggered.
+     */
+    evaluateConditions(_event, evaluator, recentEvents) {
+        const triggered = [];
+        for (const cond of this.wakeConditions) {
+            if (cond.status !== 'waiting')
+                continue;
+            if (evaluator(cond, this.board, recentEvents)) {
+                cond.status = 'triggered';
+                triggered.push(cond);
+            }
+        }
+        return triggered;
+    }
+    removeCondition(conditionId) {
+        this.wakeConditions = this.wakeConditions.filter((c) => c.id !== conditionId);
+    }
+    // ── Lifecycle ───────────────────────────────────
+    /**
+     * Export the current state as a serializable object.
+     */
+    getState() {
+        return {
+            pendingMessages: [...this.pendingMessages],
+            board: Object.fromEntries(this.board),
+            wakeConditions: [...this.wakeConditions],
+        };
+    }
+    /**
+     * Restore state from a serialized object (e.g. after thread recovery).
+     * Only board is restored — pending messages and wake conditions are transient.
+     */
+    restoreBoard(entries) {
+        this.board.clear();
+        for (const entry of entries) {
+            this.board.set(entry.key, entry);
+        }
+    }
+    /**
+     * Restore full mailbox state from a serialized MailboxState snapshot (WS5).
+     */
+    restoreFromState(state) {
+        this.pendingMessages = [...(state.pendingMessages || [])];
+        this.board.clear();
+        if (state.board) {
+            for (const [key, entry] of Object.entries(state.board)) {
+                this.board.set(key, entry);
+            }
+        }
+        this.wakeConditions = [...(state.wakeConditions || [])];
+    }
+    /**
+     * Shutdown: discard ephemeral state, return durable state.
+     */
+    shutdown() {
+        const durableBoard = this.getBoardSnapshot();
+        this.pendingMessages = [];
+        this.wakeConditions = [];
+        return { board: durableBoard };
+    }
+}

package/dist/server/services/act-runtime/safety-guard.js

@@ -0,0 +1,162 @@
+/**
+ * safety-guard.ts — Safety & Guard for Act runtime
+ *
+ * PRD §16: Event budget, loop detection, timeout, idle detection, permission checks.
+ */
+export const DEFAULT_SAFETY_CONFIG = {
+    maxEventsPerAct: 500,
+    maxMessagesPerPair: 50,
+    maxBoardUpdatesPerKey: 100,
+    quietWindowMs: 60_000, // 1 minute
+    loopDetectionThreshold: 5,
+    threadTimeoutMs: 30 * 60_000, // 30 minutes, per user turn
+};
+// ── Safety Guard ────────────────────────────────────────
+export class SafetyGuard {
+    eventCounts = new Map();
+    pairMessageCounts = new Map();
+    boardUpdateCounts = new Map();
+    recentPairs = []; // for loop detection
+    turnStartedAt;
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_SAFETY_CONFIG, ...config };
+    }
+    /**
+     * Create a SafetyGuard from an ActSafetyConfig (from ActDefinition.safety).
+     * Maps field names from the shared type to the internal SafetyConfig.
+     */
+    static fromActSafety(actSafety) {
+        if (!actSafety)
+            return new SafetyGuard();
+        return new SafetyGuard({
+            maxEventsPerAct: actSafety.maxEvents,
+            maxMessagesPerPair: actSafety.maxMessagesPerPair,
+            maxBoardUpdatesPerKey: actSafety.maxBoardUpdatesPerKey,
+            quietWindowMs: actSafety.quietWindowMs,
+            loopDetectionThreshold: actSafety.loopDetectionThreshold,
+            ...(typeof actSafety.threadTimeoutMs === 'number'
+                ? { threadTimeoutMs: actSafety.threadTimeoutMs }
+                : {}),
+        });
+    }
+    /**
+     * Check total event budget for the Act thread.
+     */
+    checkEventBudget(event) {
+        const threadKey = typeof event.payload.threadId === 'string' ? event.payload.threadId : 'default';
+        const current = (this.eventCounts.get(threadKey) || 0) + 1;
+        this.eventCounts.set(threadKey, current);
+        if (current > this.config.maxEventsPerAct) {
+            return { ok: false, reason: `Event budget exceeded (${this.config.maxEventsPerAct} max). Thread should be completed.` };
+        }
+        return { ok: true };
+    }
+    /**
+     * Check messages between a pair of performers.
+     */
+    checkPairBudget(from, to) {
+        const key = [from, to].sort().join(':');
+        const current = (this.pairMessageCounts.get(key) || 0) + 1;
+        this.pairMessageCounts.set(key, current);
+        if (current > this.config.maxMessagesPerPair) {
+            return { ok: false, reason: `Message limit between ${from} and ${to} exceeded (${this.config.maxMessagesPerPair} max).` };
+        }
+        return { ok: true };
+    }
+    /**
+     * Check board update count for a key.
+     */
+    checkBoardUpdateBudget(key) {
+        const current = (this.boardUpdateCounts.get(key) || 0) + 1;
+        this.boardUpdateCounts.set(key, current);
+        if (current > this.config.maxBoardUpdatesPerKey) {
+            return { ok: false, reason: `Board key "${key}" update limit exceeded (${this.config.maxBoardUpdatesPerKey} max).` };
+        }
+        return { ok: true };
+    }
+    /**
+     * Check for loop patterns (A→B→A→B repeated).
+     */
+    checkLoopDetection(from, to) {
+        const pair = `${from}→${to}`;
+        this.recentPairs.push(pair);
+        // Keep only recent entries
+        if (this.recentPairs.length > this.config.loopDetectionThreshold * 4) {
+            this.recentPairs = this.recentPairs.slice(-this.config.loopDetectionThreshold * 4);
+        }
+        // Detect A→B→A→B pattern
+        const reversePair = `${to}→${from}`;
+        let alternations = 0;
+        for (let i = this.recentPairs.length - 1; i >= 1; i--) {
+            const current = this.recentPairs[i];
+            const prev = this.recentPairs[i - 1];
+            if ((current === pair && prev === reversePair) || (current === reversePair && prev === pair)) {
+                alternations++;
+            }
+        }
+        if (alternations >= this.config.loopDetectionThreshold) {
+            return { ok: false, reason: `Loop detected between ${from} and ${to} (${alternations} alternations). Breaking loop.` };
+        }
+        return { ok: true };
+    }
+    /**
+     * Check thread timeout.
+     */
+    checkTimeout(thread) {
+        if (typeof this.config.threadTimeoutMs !== 'number' || this.config.threadTimeoutMs <= 0) {
+            return { ok: true };
+        }
+        const startedAt = this.turnStartedAt ?? thread.createdAt;
+        const elapsed = Date.now() - startedAt;
+        if (elapsed > this.config.threadTimeoutMs) {
+            return { ok: false, reason: `Thread timeout exceeded (${Math.round(this.config.threadTimeoutMs / 60_000)} minutes max).` };
+        }
+        return { ok: true };
+    }
+    /**
+     * Check idle condition: no pending work in mailbox or queue.
+     */
+    checkIdleCondition(mailbox, queue) {
+        const hasPending = mailbox.getAllPendingMessages().length > 0;
+        const hasQueued = queue.hasAnyPending();
+        const hasWakeConditions = mailbox.getWakeConditions().length > 0;
+        return !hasPending && !hasQueued && !hasWakeConditions;
+    }
+    /**
+     * Check permission: does a relation exist between from and to?
+     */
+    checkPermission(from, to, relations) {
+        const hasRelation = relations.some((rel) => {
+            const [a, b] = rel.between;
+            if (rel.direction === 'one-way') {
+                return a === from && b === to;
+            }
+            return (a === from && b === to) || (a === to && b === from);
+        });
+        if (!hasRelation) {
+            return { ok: false, reason: `No relation exists between "${from}" and "${to}". Cannot send message.` };
+        }
+        return { ok: true };
+    }
+    /**
+     * Check board write policy.
+     */
+    checkBoardWritePolicy(entry, author) {
+        const wp = entry.writePolicy || 'any';
+        if (wp === 'author-only' && entry.author !== author) {
+            return { ok: false, reason: `Board key "${entry.key}" is author-only and owned by "${entry.author}".` };
+        }
+        return { ok: true };
+    }
+    /**
+     * Reset all counters (for new thread).
+     */
+    reset(turnStartedAt) {
+        this.eventCounts.clear();
+        this.pairMessageCounts.clear();
+        this.boardUpdateCounts.clear();
+        this.recentPairs = [];
+        this.turnStartedAt = turnStartedAt;
+    }
+}

package/dist/server/services/act-runtime/session-queue.js

@@ -0,0 +1,114 @@
+/**
+ * session-queue.ts — Same Participant Policy queue
+ *
+ * PRD §15.4: If the same participant is already executing, queue new wake-ups.
+ * Supports coalescing rules for board key updates and sender messages.
+ */
+import { payloadString } from './act-runtime-utils.js';
+export class SessionQueue {
+    queues = new Map();
+    running = new Set();
+    /**
+     * Mark a participant as currently running.
+     */
+    markRunning(participantKey) {
+        this.running.add(participantKey);
+    }
+    /**
+     * Clear running state without draining queued work.
+     */
+    clearRunning(participantKey) {
+        this.running.delete(participantKey);
+    }
+    /**
+     * Mark a participant as no longer running. Returns the next queued wake-up if any.
+     */
+    markIdle(participantKey) {
+        this.running.delete(participantKey);
+        return this.dequeue(participantKey);
+    }
+    /**
+     * Check if a participant is currently running.
+     */
+    isRunning(participantKey) {
+        return this.running.has(participantKey);
+    }
+    /**
+     * Enqueue a wake-up for a participant. Applies coalescing rules.
+     */
+    enqueue(participantKey, wakeUp) {
+        let queue = this.queues.get(participantKey);
+        if (!queue) {
+            queue = [];
+            this.queues.set(participantKey, queue);
+        }
+        // ── Coalescing rules ────────────────────────
+        const payload = wakeUp.triggerEvent.payload;
+        // Rule 1: Same board key update → replace (latest-only)
+        if (wakeUp.triggerEvent.type === 'board.posted' || wakeUp.triggerEvent.type === 'board.updated') {
+            const key = payloadString(payload, 'key');
+            const existingIdx = queue.findIndex((entry) => {
+                const ep = entry.target.triggerEvent.payload;
+                return (entry.target.triggerEvent.type === 'board.posted' || entry.target.triggerEvent.type === 'board.updated')
+                    && payloadString(ep, 'key') === key;
+            });
+            if (existingIdx !== -1) {
+                queue[existingIdx] = { target: wakeUp, enqueuedAt: Date.now() };
+                return;
+            }
+        }
+        // Rule 2: Same sender consecutive messages → batch (replace with latest)
+        if (wakeUp.triggerEvent.type === 'message.sent') {
+            const from = payloadString(payload, 'from');
+            const tag = payloadString(payload, 'tag');
+            const existingIdx = queue.findIndex((entry) => {
+                const ep = entry.target.triggerEvent.payload;
+                return entry.target.triggerEvent.type === 'message.sent'
+                    && payloadString(ep, 'from') === from
+                    && payloadString(ep, 'tag') === tag; // Different tags are not merged
+            });
+            if (existingIdx !== -1) {
+                queue[existingIdx] = { target: wakeUp, enqueuedAt: Date.now() };
+                return;
+            }
+        }
+        // No coalescing — just append
+        queue.push({ target: wakeUp, enqueuedAt: Date.now() });
+    }
+    /**
+     * Dequeue the next wake-up for a participant.
+     */
+    dequeue(participantKey) {
+        const queue = this.queues.get(participantKey);
+        if (!queue || queue.length === 0)
+            return null;
+        const entry = queue.shift();
+        if (queue.length === 0) {
+            this.queues.delete(participantKey);
+        }
+        return entry.target;
+    }
+    /**
+     * Get the queue depth for a participant.
+     */
+    getQueueDepth(participantKey) {
+        return this.queues.get(participantKey)?.length ?? 0;
+    }
+    /**
+     * Check if any queues have pending items.
+     */
+    hasAnyPending() {
+        for (const queue of this.queues.values()) {
+            if (queue.length > 0)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Clear all queues and running state.
+     */
+    clear() {
+        this.queues.clear();
+        this.running.clear();
+    }
+}