profclaw 0.0.1-beta.1

package/dist/chat/execution/session-spawn/manager.js

@@ -0,0 +1,418 @@
+/**
+ * Agent Session Manager Implementation
+ *
+ * Database-backed manager for spawning and managing agent sessions.
+ * Supports hierarchical session trees and inter-session messaging.
+ */
+import { randomUUID } from 'crypto';
+import { eq, and, lt, inArray, desc, isNull, sql } from 'drizzle-orm';
+import { getDb } from '../../../storage/index.js';
+import { agentSessions, sessionMessages } from '../../../storage/schema.js';
+import { logger } from '../../../utils/logger.js';
+import { getSessionSpawnConfig, getRootSessionLimits } from './config.js';
+// Manager Implementation
+export class AgentSessionManagerImpl {
+    // Session Lifecycle
+    async spawn(params) {
+        const db = getDb();
+        const config = getSessionSpawnConfig();
+        // Get parent session to validate depth
+        const parent = await this.get(params.parentSessionId);
+        if (!parent) {
+            throw new Error(`Parent session not found: ${params.parentSessionId}`);
+        }
+        // Validate spawn depth
+        const newDepth = parent.depth + 1;
+        if (newDepth > config.maxDepth) {
+            throw new Error(`Cannot spawn session: max depth ${config.maxDepth} exceeded (current depth: ${parent.depth})`);
+        }
+        // Check max children
+        const existingChildren = await this.getChildren(params.parentSessionId);
+        if (existingChildren.length >= config.maxChildrenPerSession) {
+            throw new Error(`Cannot spawn session: max children ${config.maxChildrenPerSession} reached`);
+        }
+        const id = randomUUID();
+        const now = new Date();
+        const sessionData = {
+            id,
+            parentSessionId: params.parentSessionId,
+            conversationId: parent.conversationId,
+            name: params.name,
+            description: params.description ?? null,
+            goal: params.goal ?? null,
+            status: 'pending',
+            depth: newDepth,
+            currentStep: 0,
+            maxSteps: params.maxSteps ?? config.defaultSteps,
+            usedBudget: 0,
+            maxBudget: params.maxBudget ?? config.defaultBudget,
+            allowedTools: params.allowedTools ?? null,
+            disallowedTools: params.disallowedTools ?? null,
+            createdAt: now,
+            startedAt: null,
+            completedAt: null,
+            updatedAt: now,
+            finalResult: null,
+            stopReason: null,
+            metadata: params.metadata ?? {},
+        };
+        await db.insert(agentSessions).values(sessionData);
+        logger.info(`[SessionSpawn] Created child session: ${id}`, {
+            parentId: params.parentSessionId,
+            name: params.name,
+            depth: newDepth,
+        });
+        return this.mapToAgentSession(sessionData);
+    }
+    async get(sessionId) {
+        const db = getDb();
+        const rows = await db
+            .select()
+            .from(agentSessions)
+            .where(eq(agentSessions.id, sessionId))
+            .limit(1);
+        return rows[0] ? this.mapToAgentSession(rows[0]) : null;
+    }
+    async update(sessionId, params) {
+        const db = getDb();
+        const updates = {
+            updatedAt: new Date(),
+        };
+        if (params.currentStep !== undefined)
+            updates.currentStep = params.currentStep;
+        if (params.usedBudget !== undefined)
+            updates.usedBudget = params.usedBudget;
+        if (params.status !== undefined)
+            updates.status = params.status;
+        if (params.metadata !== undefined)
+            updates.metadata = params.metadata;
+        await db
+            .update(agentSessions)
+            .set(updates)
+            .where(eq(agentSessions.id, sessionId));
+        return this.get(sessionId);
+    }
+    async complete(sessionId, params) {
+        const db = getDb();
+        const now = new Date();
+        await db
+            .update(agentSessions)
+            .set({
+            status: 'completed',
+            finalResult: params.finalResult,
+            stopReason: params.stopReason,
+            completedAt: now,
+            updatedAt: now,
+        })
+            .where(eq(agentSessions.id, sessionId));
+        logger.info(`[SessionSpawn] Session completed: ${sessionId}`, {
+            stopReason: params.stopReason,
+        });
+        return this.get(sessionId);
+    }
+    async cancel(sessionId, reason) {
+        const db = getDb();
+        const now = new Date();
+        await db
+            .update(agentSessions)
+            .set({
+            status: 'cancelled',
+            stopReason: 'cancelled',
+            completedAt: now,
+            updatedAt: now,
+            metadata: reason ? { cancelReason: reason } : undefined,
+        })
+            .where(eq(agentSessions.id, sessionId));
+        logger.info(`[SessionSpawn] Session cancelled: ${sessionId}`, { reason });
+        return this.get(sessionId);
+    }
+    // Hierarchy Queries
+    async getChildren(sessionId) {
+        const db = getDb();
+        const rows = await db
+            .select()
+            .from(agentSessions)
+            .where(eq(agentSessions.parentSessionId, sessionId))
+            .orderBy(agentSessions.createdAt);
+        return rows.map((r) => this.mapToAgentSession(r));
+    }
+    async getSiblings(sessionId) {
+        const session = await this.get(sessionId);
+        if (!session || !session.parentSessionId) {
+            return [];
+        }
+        const db = getDb();
+        const rows = await db
+            .select()
+            .from(agentSessions)
+            .where(and(eq(agentSessions.parentSessionId, session.parentSessionId), sql `${agentSessions.id} != ${sessionId}`))
+            .orderBy(agentSessions.createdAt);
+        return rows.map((r) => this.mapToAgentSession(r));
+    }
+    async getParent(sessionId) {
+        const session = await this.get(sessionId);
+        if (!session || !session.parentSessionId) {
+            return null;
+        }
+        return this.get(session.parentSessionId);
+    }
+    async getByConversation(conversationId) {
+        const db = getDb();
+        const rows = await db
+            .select()
+            .from(agentSessions)
+            .where(eq(agentSessions.conversationId, conversationId))
+            .orderBy(agentSessions.createdAt);
+        return rows.map((r) => this.mapToAgentSession(r));
+    }
+    // Messaging
+    async send(params) {
+        const db = getDb();
+        const config = getSessionSpawnConfig();
+        const sentMessages = [];
+        // Resolve target session IDs
+        const targetIds = await this.resolveTargetSessionIds(params.fromSessionId, params.target);
+        if (targetIds.length === 0) {
+            logger.warn(`[SessionSpawn] No targets found for message`, {
+                fromSessionId: params.fromSessionId,
+                target: params.target,
+            });
+            return [];
+        }
+        const now = new Date();
+        const expiresAt = params.ttlMs ? new Date(now.getTime() + params.ttlMs) : null;
+        for (const toSessionId of targetIds) {
+            const id = randomUUID();
+            const messageData = {
+                id,
+                fromSessionId: params.fromSessionId,
+                toSessionId,
+                type: params.type,
+                subject: params.subject ?? null,
+                content: params.content,
+                priority: params.priority ?? config.defaultMessagePriority,
+                status: 'pending',
+                replyToMessageId: params.replyToMessageId ?? null,
+                expiresAt,
+                createdAt: now,
+                deliveredAt: null,
+                readAt: null,
+            };
+            await db.insert(sessionMessages).values(messageData);
+            sentMessages.push(this.mapToSessionMessage(messageData));
+        }
+        logger.debug(`[SessionSpawn] Sent ${sentMessages.length} messages`, {
+            fromSessionId: params.fromSessionId,
+            target: params.target,
+            type: params.type,
+        });
+        return sentMessages;
+    }
+    async receive(params) {
+        const db = getDb();
+        const now = new Date();
+        // Build query conditions
+        const conditions = [
+            eq(sessionMessages.toSessionId, params.sessionId),
+            // Exclude expired messages
+            sql `(${sessionMessages.expiresAt} IS NULL OR ${sessionMessages.expiresAt} > ${now})`,
+        ];
+        if (params.types?.length) {
+            conditions.push(inArray(sessionMessages.type, params.types));
+        }
+        if (params.fromSessionId) {
+            conditions.push(eq(sessionMessages.fromSessionId, params.fromSessionId));
+        }
+        if (params.minPriority) {
+            conditions.push(sql `${sessionMessages.priority} >= ${params.minPriority}`);
+        }
+        // By default, get unread messages
+        if (!params.markAsRead) {
+            conditions.push(isNull(sessionMessages.readAt));
+        }
+        const rows = await db
+            .select()
+            .from(sessionMessages)
+            .where(and(...conditions))
+            .orderBy(desc(sessionMessages.priority), sessionMessages.createdAt)
+            .limit(params.limit ?? 50);
+        // Mark as read if requested
+        if (params.markAsRead && rows.length > 0) {
+            const messageIds = rows.map((r) => r.id);
+            await db
+                .update(sessionMessages)
+                .set({
+                status: 'read',
+                readAt: now,
+                deliveredAt: sql `COALESCE(${sessionMessages.deliveredAt}, ${now})`,
+            })
+                .where(inArray(sessionMessages.id, messageIds));
+        }
+        return rows.map((r) => this.mapToSessionMessage(r));
+    }
+    async getUnreadCount(sessionId) {
+        const db = getDb();
+        const now = new Date();
+        const result = await db
+            .select({ count: sql `COUNT(*)` })
+            .from(sessionMessages)
+            .where(and(eq(sessionMessages.toSessionId, sessionId), isNull(sessionMessages.readAt), sql `(${sessionMessages.expiresAt} IS NULL OR ${sessionMessages.expiresAt} > ${now})`));
+        return result[0]?.count ?? 0;
+    }
+    // Cleanup
+    async cleanup(params) {
+        const db = getDb();
+        const cutoff = new Date(Date.now() - params.olderThanMs);
+        // Delete old completed/failed/cancelled sessions
+        const sessionsResult = await db
+            .delete(agentSessions)
+            .where(and(inArray(agentSessions.status, ['completed', 'failed', 'cancelled']), lt(agentSessions.completedAt, cutoff)))
+            .returning({ id: agentSessions.id });
+        // Delete expired messages
+        const now = new Date();
+        const messagesResult = await db
+            .delete(sessionMessages)
+            .where(and(sql `${sessionMessages.expiresAt} IS NOT NULL`, lt(sessionMessages.expiresAt, now)))
+            .returning({ id: sessionMessages.id });
+        const sessionsDeleted = sessionsResult.length;
+        const messagesDeleted = messagesResult.length;
+        if (sessionsDeleted > 0 || messagesDeleted > 0) {
+            logger.info(`[SessionSpawn] Cleanup complete`, {
+                sessionsDeleted,
+                messagesDeleted,
+            });
+        }
+        return { sessionsDeleted, messagesDeleted };
+    }
+    // Helper: Create Root Session
+    /**
+     * Create a root session for a conversation.
+     * This is called when starting a new agentic conversation.
+     */
+    async createRootSession(conversationId, name, goal) {
+        const db = getDb();
+        const rootLimits = getRootSessionLimits();
+        const id = randomUUID();
+        const now = new Date();
+        const sessionData = {
+            id,
+            parentSessionId: null,
+            conversationId,
+            name,
+            description: null,
+            goal: goal ?? null,
+            status: 'running',
+            depth: 0,
+            currentStep: 0,
+            maxSteps: rootLimits.maxSteps,
+            usedBudget: 0,
+            maxBudget: rootLimits.maxBudget,
+            createdAt: now,
+            startedAt: now,
+            completedAt: null,
+            updatedAt: now,
+            finalResult: null,
+            stopReason: null,
+            allowedTools: null,
+            disallowedTools: null,
+            metadata: {},
+        };
+        await db.insert(agentSessions).values(sessionData);
+        logger.info(`[SessionSpawn] Created root session: ${id}`, {
+            conversationId,
+            name,
+        });
+        return this.mapToAgentSession(sessionData);
+    }
+    // Private Helpers
+    async resolveTargetSessionIds(fromSessionId, target) {
+        switch (target) {
+            case 'parent': {
+                const parent = await this.getParent(fromSessionId);
+                return parent ? [parent.id] : [];
+            }
+            case 'children': {
+                const children = await this.getChildren(fromSessionId);
+                return children.map((c) => c.id);
+            }
+            case 'siblings': {
+                const siblings = await this.getSiblings(fromSessionId);
+                return siblings.map((s) => s.id);
+            }
+            default:
+                // Specific session ID
+                return [target];
+        }
+    }
+    mapToAgentSession(row) {
+        return {
+            id: row.id,
+            parentSessionId: row.parentSessionId,
+            conversationId: row.conversationId,
+            name: row.name,
+            description: row.description ?? undefined,
+            goal: row.goal ?? undefined,
+            status: row.status,
+            depth: row.depth,
+            currentStep: row.currentStep,
+            maxSteps: row.maxSteps,
+            usedBudget: row.usedBudget,
+            maxBudget: row.maxBudget,
+            finalResult: row.finalResult ?? undefined,
+            stopReason: row.stopReason ?? undefined,
+            allowedTools: row.allowedTools ?? undefined,
+            disallowedTools: row.disallowedTools ?? undefined,
+            createdAt: row.createdAt instanceof Date ? row.createdAt : new Date(row.createdAt),
+            startedAt: row.startedAt
+                ? row.startedAt instanceof Date
+                    ? row.startedAt
+                    : new Date(row.startedAt)
+                : undefined,
+            completedAt: row.completedAt
+                ? row.completedAt instanceof Date
+                    ? row.completedAt
+                    : new Date(row.completedAt)
+                : undefined,
+            updatedAt: row.updatedAt instanceof Date ? row.updatedAt : new Date(row.updatedAt),
+            metadata: row.metadata ?? undefined,
+        };
+    }
+    mapToSessionMessage(row) {
+        return {
+            id: row.id,
+            fromSessionId: row.fromSessionId,
+            toSessionId: row.toSessionId,
+            type: row.type,
+            subject: row.subject ?? undefined,
+            content: row.content,
+            priority: row.priority,
+            status: row.status,
+            replyToMessageId: row.replyToMessageId ?? undefined,
+            expiresAt: row.expiresAt
+                ? row.expiresAt instanceof Date
+                    ? row.expiresAt
+                    : new Date(row.expiresAt)
+                : undefined,
+            createdAt: row.createdAt instanceof Date ? row.createdAt : new Date(row.createdAt),
+            deliveredAt: row.deliveredAt
+                ? row.deliveredAt instanceof Date
+                    ? row.deliveredAt
+                    : new Date(row.deliveredAt)
+                : undefined,
+            readAt: row.readAt
+                ? row.readAt instanceof Date
+                    ? row.readAt
+                    : new Date(row.readAt)
+                : undefined,
+        };
+    }
+}
+// Singleton
+let managerInstance = null;
+export function getAgentSessionManager() {
+    if (!managerInstance) {
+        managerInstance = new AgentSessionManagerImpl();
+    }
+    return managerInstance;
+}
+//# sourceMappingURL=manager.js.map

package/dist/chat/execution/session-spawn/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Session Spawn Types
+ *
+ * Type definitions for the agent session hierarchy and messaging system.
+ * Enables parent agents to spawn child sessions for parallel work.
+ */
+export type SessionStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+export type SessionStopReason = 'completed' | 'budget_exceeded' | 'max_steps' | 'cancelled' | 'error' | 'timeout';
+export interface AgentSession {
+    id: string;
+    parentSessionId: string | null;
+    conversationId: string;
+    name: string;
+    description?: string;
+    goal?: string;
+    status: SessionStatus;
+    depth: number;
+    currentStep: number;
+    maxSteps: number;
+    usedBudget: number;
+    maxBudget: number;
+    finalResult?: Record<string, unknown>;
+    stopReason?: SessionStopReason;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    createdAt: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+    updatedAt: Date;
+    metadata?: Record<string, unknown>;
+}
+export type MessageType = 'message' | 'result' | 'request' | 'notification' | 'error';
+export type MessageStatus = 'pending' | 'delivered' | 'read' | 'expired';
+export interface SessionMessage {
+    id: string;
+    fromSessionId: string;
+    toSessionId: string;
+    type: MessageType;
+    subject?: string;
+    content: Record<string, unknown>;
+    priority: number;
+    status: MessageStatus;
+    replyToMessageId?: string;
+    expiresAt?: Date;
+    createdAt: Date;
+    deliveredAt?: Date;
+    readAt?: Date;
+}
+export interface SpawnSessionParams {
+    parentSessionId: string;
+    name: string;
+    goal: string;
+    description?: string;
+    maxSteps?: number;
+    maxBudget?: number;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface UpdateSessionParams {
+    currentStep?: number;
+    usedBudget?: number;
+    status?: SessionStatus;
+    metadata?: Record<string, unknown>;
+}
+export interface CompleteSessionParams {
+    finalResult: Record<string, unknown>;
+    stopReason: SessionStopReason;
+}
+export interface SendMessageParams {
+    fromSessionId: string;
+    target: 'parent' | 'children' | 'siblings' | string;
+    type: MessageType;
+    subject?: string;
+    content: Record<string, unknown>;
+    priority?: number;
+    replyToMessageId?: string;
+    ttlMs?: number;
+}
+export interface ReceiveMessagesParams {
+    sessionId: string;
+    types?: MessageType[];
+    fromSessionId?: string;
+    minPriority?: number;
+    markAsRead?: boolean;
+    limit?: number;
+}
+export interface CleanupParams {
+    olderThanMs: number;
+}
+export interface AgentSessionManager {
+    spawn(params: SpawnSessionParams): Promise<AgentSession>;
+    get(sessionId: string): Promise<AgentSession | null>;
+    update(sessionId: string, params: UpdateSessionParams): Promise<AgentSession | null>;
+    complete(sessionId: string, params: CompleteSessionParams): Promise<AgentSession | null>;
+    cancel(sessionId: string, reason?: string): Promise<AgentSession | null>;
+    getChildren(sessionId: string): Promise<AgentSession[]>;
+    getSiblings(sessionId: string): Promise<AgentSession[]>;
+    getParent(sessionId: string): Promise<AgentSession | null>;
+    getByConversation(conversationId: string): Promise<AgentSession[]>;
+    send(params: SendMessageParams): Promise<SessionMessage[]>;
+    receive(params: ReceiveMessagesParams): Promise<SessionMessage[]>;
+    getUnreadCount(sessionId: string): Promise<number>;
+    cleanup(params: CleanupParams): Promise<{
+        sessionsDeleted: number;
+        messagesDeleted: number;
+    }>;
+}
+export declare const SESSION_CONSTANTS: {
+    readonly MAX_SPAWN_DEPTH: 3;
+    readonly MAX_CHILDREN_PER_SESSION: 5;
+    readonly DEFAULT_MAX_STEPS: 20;
+    readonly DEFAULT_MAX_BUDGET: 20000;
+    readonly DEFAULT_MESSAGE_PRIORITY: 5;
+    readonly MAX_MESSAGE_PRIORITY: 10;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/chat/execution/session-spawn/types.js

@@ -0,0 +1,16 @@
+/**
+ * Session Spawn Types
+ *
+ * Type definitions for the agent session hierarchy and messaging system.
+ * Enables parent agents to spawn child sessions for parallel work.
+ */
+// Constants
+export const SESSION_CONSTANTS = {
+    MAX_SPAWN_DEPTH: 3,
+    MAX_CHILDREN_PER_SESSION: 5,
+    DEFAULT_MAX_STEPS: 20,
+    DEFAULT_MAX_BUDGET: 20_000,
+    DEFAULT_MESSAGE_PRIORITY: 5,
+    MAX_MESSAGE_PRIORITY: 10,
+};
+//# sourceMappingURL=types.js.map

package/dist/chat/execution/smart-prompts.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Smart System Prompts
+ *
+ * Generates adaptive system prompt segments based on model capability level.
+ * Large models get high-level goals, small models get explicit step-by-step
+ * instructions with examples. This makes profClaw work well regardless of
+ * which AI model is being used.
+ */
+import type { ModelCapabilityLevel } from './types.js';
+/**
+ * Estimate token count for a string (rough: 4 chars per token).
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Truncate conversation history to fit within a token budget.
+ * Keeps the most recent messages and the system prompt.
+ */
+export declare function truncateHistory(messages: Array<{
+    role: string;
+    content: string;
+}>, maxTokens: number): Array<{
+    role: string;
+    content: string;
+}>;
+/**
+ * Build adaptive tool usage prompt segment for the given model capability.
+ */
+export declare function buildToolPrompt(capability: ModelCapabilityLevel): string;
+/**
+ * Get the recommended context window usage for history,
+ * leaving room for tool schemas and response.
+ */
+export declare function getHistoryBudget(contextWindow: number, capability: ModelCapabilityLevel): number;
+//# sourceMappingURL=smart-prompts.d.ts.map