dot-studio 0.0.1 → 0.0.2

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

@@ -0,0 +1,313 @@
+import { nanoid } from 'nanoid';
+import { SafetyGuard } from './safety-guard.js';
+import { ThreadManager } from './thread-manager.js';
+import { clearParticipantCircuit, clearParticipantQueueRunning, drainParticipantQueueAfterSettlement, markParticipantQueueRunning, processWakeCascade, tripParticipantCircuit, } from './wake-cascade.js';
+import { workspaceIdForDir } from '../../lib/config.js';
+function errorMessage(error) {
+    return error instanceof Error ? error.message : 'Unknown error';
+}
+class ActRuntimeService {
+    threadManager;
+    workingDir;
+    safetyGuards = new Map();
+    _threadsLoaded = false;
+    constructor(workspaceId, workingDir) {
+        this.workingDir = workingDir;
+        this.threadManager = new ThreadManager(workspaceId, workingDir);
+    }
+    /** Lazy-load persisted threads on first access */
+    async ensureThreadsLoaded() {
+        if (this._threadsLoaded)
+            return;
+        this._threadsLoaded = true;
+        console.log(`[act-runtime] Loading persisted threads for workspace ${this.workingDir}`);
+        await this.threadManager.loadPersistedThreads();
+        console.log(`[act-runtime] Loaded ${this.threadManager.getActiveThreadCount()} threads`);
+    }
+    getSafetyGuard(threadId) {
+        if (!this.safetyGuards.has(threadId)) {
+            const actDef = this.threadManager.getActDefinition(threadId);
+            this.safetyGuards.set(threadId, SafetyGuard.fromActSafety(actDef?.safety));
+        }
+        return this.safetyGuards.get(threadId);
+    }
+    async sendMessage(threadId, body) {
+        await this.ensureThreadsLoaded();
+        const runtime = this.threadManager.getThreadRuntime(threadId);
+        if (!runtime) {
+            console.error(`[act-runtime] sendMessage: Thread ${threadId} not found. workingDir=${this.workingDir}`);
+            return { ok: false, status: 404, error: `Thread ${threadId} not found` };
+        }
+        const guard = this.getSafetyGuard(threadId);
+        // Thread timeout check (PRD §16.3)
+        const timeoutCheck = guard.checkTimeout(runtime.thread);
+        if (!timeoutCheck.ok) {
+            return { ok: false, status: 429, error: timeoutCheck.reason };
+        }
+        // Event budget check BEFORE message is added (PRD §16.1)
+        const preEvent = {
+            id: nanoid(),
+            type: 'message.sent',
+            sourceType: 'performer',
+            source: body.from,
+            timestamp: Date.now(),
+            payload: { from: body.from, to: body.to, tag: body.tag, threadId },
+        };
+        const budgetCheck = guard.checkEventBudget(preEvent);
+        if (!budgetCheck.ok) {
+            return { ok: false, status: 429, error: budgetCheck.reason };
+        }
+        // Relation permission check (PRD §16.5)
+        const actDefinition = this.threadManager.getActDefinition(threadId);
+        if (actDefinition) {
+            const permCheck = guard.checkPermission(body.from, body.to, actDefinition.relations);
+            if (!permCheck.ok) {
+                return { ok: false, status: 403, error: permCheck.reason };
+            }
+        }
+        const pairCheck = guard.checkPairBudget(body.from, body.to);
+        if (!pairCheck.ok) {
+            return { ok: false, status: 429, error: pairCheck.reason };
+        }
+        const loopCheck = guard.checkLoopDetection(body.from, body.to);
+        if (!loopCheck.ok) {
+            return { ok: false, status: 429, error: loopCheck.reason };
+        }
+        const message = runtime.mailbox.addMessage({
+            from: body.from,
+            to: body.to,
+            content: body.content,
+            tag: body.tag,
+            threadId,
+        });
+        // Update event with messageId and log
+        preEvent.payload = { messageId: message.id, from: body.from, to: body.to, tag: body.tag, threadId };
+        await this.threadManager.logEvent(threadId, preEvent);
+        // Fire-and-forget: don't block the tool call response
+        if (actDefinition) {
+            processWakeCascade(preEvent, actDefinition, runtime.mailbox, this.threadManager, threadId, this.workingDir)
+                .then((cascadeResult) => this.maybeEmitRuntimeIdle(threadId, cascadeResult, actDefinition, runtime.mailbox))
+                .catch((err) => console.error('[act-runtime] Wake cascade error (sendMessage):', err));
+        }
+        return { ok: true, messageId: message.id };
+    }
+    async postToBoard(threadId, body) {
+        await this.ensureThreadsLoaded();
+        const runtime = this.threadManager.getThreadRuntime(threadId);
+        if (!runtime) {
+            return { ok: false, status: 404, error: `Thread ${threadId} not found` };
+        }
+        const guard = this.getSafetyGuard(threadId);
+        // Thread timeout check (PRD §16.3)
+        const timeoutCheck = guard.checkTimeout(runtime.thread);
+        if (!timeoutCheck.ok) {
+            return { ok: false, status: 429, error: timeoutCheck.reason };
+        }
+        const boardCheck = guard.checkBoardUpdateBudget(body.key);
+        if (!boardCheck.ok) {
+            return { ok: false, status: 429, error: boardCheck.reason };
+        }
+        // Board writePolicy check (PRD §16.6)
+        const existingEntry = runtime.mailbox.readBoard(body.key);
+        if (existingEntry) {
+            const wpCheck = guard.checkBoardWritePolicy(existingEntry, body.author);
+            if (!wpCheck.ok) {
+                return { ok: false, status: 403, error: wpCheck.reason };
+            }
+        }
+        try {
+            const entry = runtime.mailbox.postToBoard({
+                key: body.key,
+                kind: body.kind,
+                author: body.author,
+                content: body.content,
+                updateMode: body.updateMode || 'replace',
+                ownership: 'authoritative',
+                metadata: body.metadata,
+                threadId,
+            });
+            await this.threadManager.persistBoard(threadId);
+            const existing = runtime.mailbox.readBoard(body.key);
+            const eventType = (existing?.version ?? 0) > 1 ? 'board.updated' : 'board.posted';
+            const event = {
+                id: nanoid(),
+                type: eventType,
+                sourceType: 'performer',
+                source: body.author,
+                timestamp: Date.now(),
+                payload: { key: body.key, kind: body.kind, author: body.author, threadId },
+            };
+            await this.threadManager.logEvent(threadId, event);
+            const actDefinition = this.threadManager.getActDefinition(threadId);
+            // Fire-and-forget: don't block the tool call response
+            if (actDefinition) {
+                processWakeCascade(event, actDefinition, runtime.mailbox, this.threadManager, threadId, this.workingDir)
+                    .then((cascadeResult) => this.maybeEmitRuntimeIdle(threadId, cascadeResult, actDefinition, runtime.mailbox))
+                    .catch((err) => console.error('[act-runtime] Wake cascade error (postToBoard):', err));
+            }
+            return { ok: true, entryId: entry.id, version: entry.version };
+        }
+        catch (error) {
+            return { ok: false, status: 403, error: errorMessage(error) };
+        }
+    }
+    async readBoard(threadId, key) {
+        await this.ensureThreadsLoaded();
+        const runtime = this.threadManager.getThreadRuntime(threadId);
+        if (!runtime) {
+            return { ok: false, status: 404, error: `Thread ${threadId} not found` };
+        }
+        if (key) {
+            const entry = runtime.mailbox.readBoard(key);
+            return { ok: true, entries: entry ? [entry] : [] };
+        }
+        return { ok: true, entries: runtime.mailbox.getBoardSnapshot() };
+    }
+    async syncActDefinition(actId, actDefinition) {
+        await this.ensureThreadsLoaded();
+        const threadIds = this.threadManager.listThreadIds(actId, ['active', 'idle']);
+        for (const threadId of threadIds) {
+            const synced = await this.threadManager.syncThreadActDefinition(threadId, actDefinition);
+            if (!synced)
+                continue;
+            this.safetyGuards.delete(threadId);
+            const event = {
+                id: nanoid(),
+                type: 'runtime.reconfigured',
+                sourceType: 'system',
+                source: 'studio',
+                timestamp: Date.now(),
+                payload: {
+                    actId,
+                    threadId,
+                    participantCount: Object.keys(actDefinition.participants || {}).length,
+                    relationCount: actDefinition.relations.length,
+                },
+            };
+            await this.threadManager.logEvent(threadId, event);
+        }
+        return { ok: true, threads: this.threadManager.listThreads(actId) };
+    }
+    async setWakeCondition(threadId, body) {
+        await this.ensureThreadsLoaded();
+        const runtime = this.threadManager.getThreadRuntime(threadId);
+        if (!runtime) {
+            return { ok: false, status: 404, error: `Thread ${threadId} not found` };
+        }
+        const wakeCondition = runtime.mailbox.addWakeCondition({
+            target: body.target,
+            createdBy: body.createdBy,
+            onSatisfiedMessage: body.onSatisfiedMessage,
+            condition: body.condition,
+        });
+        return { ok: true, conditionId: wakeCondition.id };
+    }
+    async createThread(actId, actDefinition) {
+        const thread = await this.threadManager.createThread(actId, actDefinition);
+        return { ok: true, thread };
+    }
+    async getActDefinition(threadId) {
+        await this.ensureThreadsLoaded();
+        return this.threadManager.getActDefinition(threadId);
+    }
+    async listThreads(actId) {
+        await this.ensureThreadsLoaded();
+        return { ok: true, threads: this.threadManager.listThreads(actId) };
+    }
+    async deleteThread(_actId, threadId) {
+        const deleted = await this.threadManager.deleteThread(threadId);
+        if (!deleted) {
+            return { ok: false, status: 404, error: `Thread ${threadId} not found` };
+        }
+        return { ok: true };
+    }
+    async getThread(threadId) {
+        await this.ensureThreadsLoaded();
+        const thread = this.threadManager.getThread(threadId);
+        if (!thread) {
+            return { ok: false, status: 404, error: `Thread ${threadId} not found` };
+        }
+        return { ok: true, thread };
+    }
+    async getRecentEvents(threadId, count = 50) {
+        await this.ensureThreadsLoaded();
+        const events = await this.threadManager.getRecentEvents(threadId, count);
+        return { ok: true, events };
+    }
+    async registerParticipantSession(threadId, participantKey, sessionId) {
+        await this.ensureThreadsLoaded();
+        await this.threadManager.getOrCreateSession(threadId, participantKey, () => sessionId);
+    }
+    async beginUserTurn(threadId) {
+        await this.ensureThreadsLoaded();
+        this.getSafetyGuard(threadId).reset(Date.now());
+    }
+    async markParticipantSessionBusy(threadId, participantKey) {
+        await this.ensureThreadsLoaded();
+        markParticipantQueueRunning(threadId, participantKey);
+    }
+    async clearParticipantSessionBusy(threadId, participantKey) {
+        await this.ensureThreadsLoaded();
+        clearParticipantQueueRunning(threadId, participantKey);
+    }
+    async tripParticipantAutoWakeCircuit(threadId, participantKey, reason) {
+        await this.ensureThreadsLoaded();
+        tripParticipantCircuit(threadId, participantKey, reason);
+    }
+    async clearParticipantAutoWakeCircuit(threadId, participantKey) {
+        await this.ensureThreadsLoaded();
+        clearParticipantCircuit(threadId, participantKey);
+    }
+    async drainParticipantQueue(threadId, participantKey) {
+        await this.ensureThreadsLoaded();
+        const runtime = this.threadManager.getThreadRuntime(threadId);
+        const actDefinition = this.threadManager.getActDefinition(threadId);
+        if (!runtime || !actDefinition) {
+            return;
+        }
+        await drainParticipantQueueAfterSettlement(participantKey, actDefinition, runtime.mailbox, this.threadManager, threadId, this.workingDir);
+    }
+    /**
+     * Emit runtime.idle event when a wake cascade completes with no errors
+     * and no queued targets remaining. Participants subscribed to 'runtime.idle'
+     * will be woken by this event.
+     */
+    async maybeEmitRuntimeIdle(threadId, cascadeResult, actDefinition, mailbox) {
+        // Only emit if cascade had targets but no errors, and queue is empty
+        if (cascadeResult.errors.length > 0)
+            return;
+        if (cascadeResult.injected.length === 0 && cascadeResult.queued.length === 0)
+            return;
+        const idleEvent = {
+            id: nanoid(),
+            type: 'runtime.idle',
+            sourceType: 'system',
+            source: 'runtime',
+            timestamp: Date.now(),
+            payload: {
+                threadId,
+                injectedCount: cascadeResult.injected.length,
+            },
+        };
+        await this.threadManager.logEvent(threadId, idleEvent);
+        // Route the idle event — but don't recurse further to avoid infinite loops
+        const runtime = this.threadManager.getThreadRuntime(threadId);
+        if (runtime) {
+            processWakeCascade(idleEvent, actDefinition, mailbox, this.threadManager, threadId, this.workingDir)
+                .catch((err) => console.error('[act-runtime] Wake cascade error (runtime.idle):', err));
+        }
+    }
+}
+const runtimeServices = new Map();
+export function getActRuntimeService(workingDir) {
+    const workspaceId = workspaceIdForDir(workingDir);
+    let service = runtimeServices.get(workspaceId);
+    if (!service) {
+        service = new ActRuntimeService(workspaceId, workingDir);
+        runtimeServices.set(workspaceId, service);
+    }
+    return service;
+}
+export async function getActDefinitionForThread(workingDir, threadId) {
+    return getActRuntimeService(workingDir).getActDefinition(threadId);
+}

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

@@ -0,0 +1,10 @@
+/**
+ * act-runtime-utils.ts — Shared utilities for Act runtime modules.
+ */
+/**
+ * Safely extract a string value from an untyped payload record.
+ */
+export function payloadString(payload, key) {
+    const value = payload[key];
+    return typeof value === 'string' ? value : undefined;
+}

package/dist/server/services/act-runtime/act-tool-projection.js

@@ -0,0 +1,26 @@
+/**
+ * act-tool-projection.ts — Act tool projection for participant sessions
+ *
+ * Projects collaboration tools and stable collaboration context into participant sessions.
+ *
+ * Tools are generic static files. Stable collaboration context is intended
+ * for agent/system-level injection rather than per-turn user prompt injection.
+ */
+import { getStaticActTools } from './act-tools.js';
+import { buildActContext } from './act-context-builder.js';
+// ── Projection ──────────────────────────────────────────
+/**
+ * Generate Act tool projection for a participant in a thread.
+ * Creates tool definitions and stable collaboration context.
+ */
+export function projectActTools(participantKey, actDefinition, threadId, workingDir) {
+    void threadId;
+    // 1. Stable collaboration context for agent/system injection
+    const contextPrompt = buildActContext(actDefinition, participantKey);
+    // 2. Static session-bound tool definitions (only workingDir is baked in)
+    const tools = getStaticActTools(workingDir);
+    return {
+        contextPrompt,
+        tools,
+    };
+}

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

@@ -0,0 +1,151 @@
+/**
+ * act-tools.ts — Act runtime custom tool definitions
+ *
+ * PRD §13: Collaboration tools exposed to participants.
+ * - message_teammate
+ * - update_shared_board
+ * - read_shared_board
+ * - wait_until
+ *
+ * These are 4 generic static tool files placed in .opencode/tools/.
+ * The model only provides high-level collaboration inputs.
+ * Act/thread/participant identity is resolved from the current session.
+ */
+import { PORT } from '../../lib/config.js';
+export const COLLABORATION_TOOL_NAMES = [
+    'message_teammate',
+    'update_shared_board',
+    'read_shared_board',
+    'wait_until',
+];
+export const LEGACY_COLLABORATION_TOOL_NAMES = [
+    'act_send_message',
+    'act_post_to_board',
+    'act_read_board',
+    'act_set_wake_condition',
+];
+// ── Static tool definitions ─────────────────────────────
+/**
+ * The 4 generic Act runtime tools.
+ * These are static and session-bound.
+ * The workingDir is baked in at write time (changes per workspace, not per thread).
+ */
+export function getStaticActTools(workingDir) {
+    const wd = encodeURIComponent(workingDir);
+    const base = `http://localhost:${PORT}`;
+    return [
+        {
+            name: 'message_teammate',
+            content: `import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+    description: "Send a direct message to a teammate. Use this for targeted coordination when only one teammate needs the update.",
+    args: {
+        recipient: tool.schema.string().describe("Teammate name to message directly"),
+        message: tool.schema.string().describe("Message to send"),
+        tag: tool.schema.string().optional().describe("Optional short label for the message"),
+    },
+    async execute(args, context) {
+        const sessionID = context.sessionID
+        const res = await fetch(\`${base}/api/act/session/\${encodeURIComponent(sessionID)}/message-teammate?workingDir=${wd}\`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                recipient: args.recipient,
+                message: args.message,
+                tag: args.tag,
+            }),
+        })
+        const data = await res.json()
+        if (!data.ok) return data.error
+        return "Direct message sent."
+    },
+})
+`,
+        },
+        {
+            name: 'update_shared_board',
+            content: `import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+    description: "Create or update a shared note for the whole team. Use this for durable context, decisions, findings, and handoffs.",
+    args: {
+        entryKey: tool.schema.string().describe("Stable key for the shared note, such as api-spec or review-report"),
+        entryType: tool.schema.enum(["artifact", "fact", "task"]).describe("Type of shared note"),
+        content: tool.schema.string().describe("Entry content"),
+        mode: tool.schema.enum(["replace", "append"]).optional().describe("Whether to replace or append to an existing shared note"),
+    },
+    async execute(args, context) {
+        const sessionID = context.sessionID
+        const res = await fetch(\`${base}/api/act/session/\${encodeURIComponent(sessionID)}/update-shared-board?workingDir=${wd}\`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                entryKey: args.entryKey,
+                entryType: args.entryType,
+                content: args.content,
+                mode: args.mode,
+            }),
+        })
+        const data = await res.json()
+        if (!data.ok) return data.error
+        return "Shared note updated."
+    },
+})
+`,
+        },
+        {
+            name: 'read_shared_board',
+            content: `import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+    description: "Read shared notes created by the team. Returns matching entries as JSON.",
+    args: {
+        entryKey: tool.schema.string().optional().describe("Optional shared note key. Omit to read all shared notes."),
+    },
+    async execute(args, context) {
+        const sessionID = context.sessionID
+        const params = args.entryKey ? "&key=" + encodeURIComponent(args.entryKey) : ""
+        const res = await fetch(\`${base}/api/act/session/\${encodeURIComponent(sessionID)}/read-shared-board?workingDir=${wd}\` + params)
+        const data = await res.json()
+        if (!data.ok) return data.error
+        return JSON.stringify(data.entries, null, 2)
+    },
+})
+`,
+        },
+        {
+            name: 'wait_until',
+            content: `import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+    description: "Pause until a condition is met, then resume with the provided instruction. Use this when you are waiting for more input or a shared update.",
+    args: {
+        resumeWith: tool.schema.string().describe("Instruction to receive when the wait is over"),
+        conditionJson: tool.schema.string().describe("JSON condition expression. Supported types: all_of, any_of, board_key_exists, message_received, timeout"),
+    },
+    async execute(args, context) {
+        let condition
+        try {
+            condition = JSON.parse(args.conditionJson)
+        } catch {
+            return "Error: conditionJson must be valid JSON"
+        }
+        const sessionID = context.sessionID
+        const res = await fetch(\`${base}/api/act/session/\${encodeURIComponent(sessionID)}/wait-until?workingDir=${wd}\`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                resumeWith: args.resumeWith,
+                condition,
+            }),
+        })
+        const data = await res.json()
+        if (!data.ok) return data.error
+        return "Wait condition saved. You will resume when it is satisfied."
+    },
+})
+`,
+        },
+    ];
+}

package/dist/server/services/act-runtime/board-persistence.js

@@ -0,0 +1,38 @@
+/**
+ * board-persistence.ts — Board file persistence
+ *
+ * PRD §6.2: Board is durable — persisted to file and survives shutdown.
+ * Path: ~/.dot-studio/workspaces/<workspaceId>/act-runtime/<actId>/<threadId>/board.json
+ */
+import { promises as fs } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { workspaceActRuntimeDir } from '../../lib/config.js';
+function isErrnoException(error) {
+    return error instanceof Error;
+}
+function boardFilePath(workspaceId, actId, threadId) {
+    return join(workspaceActRuntimeDir(workspaceId, actId, threadId), 'board.json');
+}
+/**
+ * Save board entries to file.
+ */
+export async function saveBoardToFile(workspaceId, actId, threadId, entries) {
+    const filePath = boardFilePath(workspaceId, actId, threadId);
+    await fs.mkdir(dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(entries, null, 2), 'utf-8');
+}
+/**
+ * Load board entries from file.
+ */
+export async function loadBoardFromFile(workspaceId, actId, threadId) {
+    const filePath = boardFilePath(workspaceId, actId, threadId);
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}

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

@@ -0,0 +1,73 @@
+/**
+ * event-logger.ts — Append-only event log for Act Thread
+ *
+ * PRD §6.3: Events are stored as append-only .jsonl files.
+ * Path: ~/.dot-studio/workspaces/<workspaceId>/act-runtime/<actId>/<threadId>/events.jsonl
+ */
+import { promises as fs } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { workspaceActRuntimeDir } from '../../lib/config.js';
+function isErrnoException(error) {
+    return error instanceof Error;
+}
+// ── EventLogger ─────────────────────────────────────────
+export class EventLogger {
+    logPath;
+    _workspaceId;
+    _actId;
+    _threadId;
+    constructor(workspaceId, actId, threadId) {
+        this._workspaceId = workspaceId;
+        this._actId = actId;
+        this._threadId = threadId;
+        this.logPath = join(workspaceActRuntimeDir(workspaceId, actId, threadId), 'events.jsonl');
+    }
+    /**
+     * Append an event to the log file.
+     */
+    async appendEvent(event) {
+        await fs.mkdir(dirname(this.logPath), { recursive: true });
+        const line = JSON.stringify(event) + '\n';
+        await fs.appendFile(this.logPath, line, 'utf-8');
+    }
+    /**
+     * Read the last N events from the log (for UI Activity View).
+     */
+    async tailEvents(count) {
+        try {
+            const content = await fs.readFile(this.logPath, 'utf-8');
+            const lines = content.trim().split('\n').filter(Boolean);
+            const tail = lines.slice(-count);
+            return tail.map((line) => JSON.parse(line));
+        }
+        catch (error) {
+            if (isErrnoException(error) && error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+    }
+    /**
+     * Read all events from the log.
+     */
+    async readAllEvents() {
+        try {
+            const content = await fs.readFile(this.logPath, 'utf-8');
+            const lines = content.trim().split('\n').filter(Boolean);
+            return lines.map((line) => JSON.parse(line));
+        }
+        catch (error) {
+            if (isErrnoException(error) && error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+    }
+    /**
+     * Get the file path for this event log.
+     */
+    getLogPath() {
+        return this.logPath;
+    }
+    get workspaceId() { return this._workspaceId; }
+    get actId() { return this._actId; }
+    get threadId() { return this._threadId; }
+}