profclaw 2.0.0 → 2.3.0

package/dist/chat/execution/tools/repl-tool.d.ts

@@ -0,0 +1,46 @@
+/**
+ * REPL Tool
+ *
+ * Execute code in persistent REPL sessions.
+ * State (variables, imports) survives between calls within the same session.
+ * Supports Node.js and Python 3.
+ */
+import { z } from 'zod';
+import type { ChildProcess } from 'child_process';
+import type { ToolDefinition } from '../types.js';
+export interface REPLSession {
+    id: string;
+    language: 'node' | 'python';
+    process: ChildProcess;
+    output: string[];
+    createdAt: number;
+}
+export interface REPLResult {
+    output: string;
+    sessionId: string;
+    language: 'node' | 'python';
+    error?: string;
+}
+declare const ReplExecuteParamsSchema: z.ZodObject<{
+    code: z.ZodString;
+    language: z.ZodDefault<z.ZodEnum<["node", "python"]>>;
+    sessionId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    language: "node" | "python";
+    sessionId?: string | undefined;
+}, {
+    code: string;
+    sessionId?: string | undefined;
+    language?: "node" | "python" | undefined;
+}>;
+export type ReplExecuteParams = z.infer<typeof ReplExecuteParamsSchema>;
+export declare const replTool: ToolDefinition<ReplExecuteParams, REPLResult>;
+/** List all active REPL session IDs */
+export declare function listReplSessions(): string[];
+/** Terminate and remove a session by ID */
+export declare function closeReplSession(id: string): boolean;
+/** Exposed for tests — direct access to the internal session map */
+export declare function getReplSessionsMap(): Map<string, REPLSession>;
+export {};
+//# sourceMappingURL=repl-tool.d.ts.map

package/dist/chat/execution/tools/repl-tool.js

@@ -0,0 +1,207 @@
+/**
+ * REPL Tool
+ *
+ * Execute code in persistent REPL sessions.
+ * State (variables, imports) survives between calls within the same session.
+ * Supports Node.js and Python 3.
+ */
+import { z } from 'zod';
+import { spawn } from 'child_process';
+import { randomUUID } from 'node:crypto';
+import { logger } from '../../../utils/logger.js';
+// Module-level session registry
+const sessions = new Map();
+// Constants
+const REPL_TIMEOUT_MS = 30_000;
+const MAX_OUTPUT_CHARS = 50_000;
+const MAX_OUTPUT_HISTORY = 50;
+// Prompt patterns that indicate the REPL is ready for next input
+const NODE_PROMPT_RE = /^> $/m;
+const PYTHON_PROMPT_RE = /^>>> $/m;
+/**
+ * Retrieve an existing session or create a new one.
+ */
+function getOrCreateSession(language, sessionId) {
+    if (sessionId) {
+        const existing = sessions.get(sessionId);
+        if (existing)
+            return existing;
+    }
+    const id = sessionId ?? randomUUID();
+    const command = language === 'node' ? 'node' : 'python3';
+    const args = language === 'node' ? ['-i'] : ['-i', '-u'];
+    const proc = spawn(command, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env },
+    });
+    const session = {
+        id,
+        language,
+        process: proc,
+        output: [],
+        createdAt: Date.now(),
+    };
+    proc.on('close', () => {
+        sessions.delete(id);
+        logger.debug(`[ReplTool] Session ${id} closed`, { component: 'ReplTool' });
+    });
+    proc.on('error', (err) => {
+        logger.warn(`[ReplTool] Session ${id} process error: ${err.message}`, { component: 'ReplTool' });
+        sessions.delete(id);
+    });
+    sessions.set(id, session);
+    logger.debug(`[ReplTool] Created session ${id} (${language})`, { component: 'ReplTool' });
+    return session;
+}
+/**
+ * Write code to a REPL session and collect output until the prompt reappears.
+ * Returns a promise that resolves with the captured output string.
+ */
+function executeInSession(session, code) {
+    return new Promise((resolve, reject) => {
+        const { process: proc, language } = session;
+        const promptRe = language === 'node' ? NODE_PROMPT_RE : PYTHON_PROMPT_RE;
+        if (!proc.stdin || !proc.stdout || !proc.stderr) {
+            reject(new Error('REPL process streams unavailable'));
+            return;
+        }
+        let collected = '';
+        let settled = false;
+        const settle = (result, err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeoutHandle);
+            proc.stdout?.removeListener('data', onData);
+            proc.stderr?.removeListener('data', onData);
+            if (err) {
+                reject(err);
+            }
+            else {
+                resolve(result);
+            }
+        };
+        const onData = (chunk) => {
+            collected += chunk.toString();
+            // Truncate if runaway output
+            if (collected.length > MAX_OUTPUT_CHARS) {
+                collected = `[...truncated...]\n${collected.slice(-MAX_OUTPUT_CHARS)}`;
+            }
+            // Check for the prompt — indicates execution is complete
+            if (promptRe.test(collected)) {
+                // Strip the trailing prompt line from the output
+                const cleaned = collected.replace(/\n?> $|\n?>>> $/m, '').trim();
+                settle(cleaned);
+            }
+        };
+        const timeoutHandle = setTimeout(() => {
+            settle('', new Error(`REPL execution timed out after ${REPL_TIMEOUT_MS / 1000}s`));
+        }, REPL_TIMEOUT_MS);
+        proc.stdout.on('data', onData);
+        proc.stderr.on('data', onData);
+        // Send code followed by a newline so the REPL executes it
+        const input = code.endsWith('\n') ? code : `${code}\n`;
+        proc.stdin.write(input);
+    });
+}
+// Schema
+const ReplExecuteParamsSchema = z.object({
+    code: z.string().min(1).describe('Code to execute in the REPL'),
+    language: z.enum(['node', 'python']).default('node').describe('REPL language runtime'),
+    sessionId: z.string().optional().describe('Reuse an existing session ID. Omit to create a new session.'),
+});
+// Tool Definition
+export const replTool = {
+    name: 'repl_execute',
+    description: `Execute code in a persistent REPL session. State persists between calls (variables, imports stay alive). Use for iterative exploration, testing code snippets, or running multi-step computations.
+
+Examples:
+- node: assign variables, require modules, test expressions
+- python: import libraries, define functions, explore data
+
+The sessionId returned can be passed back to reuse the same session.`,
+    category: 'execution',
+    securityLevel: 'dangerous',
+    parameters: ReplExecuteParamsSchema,
+    examples: [
+        { description: 'Run a Node.js snippet', params: { code: 'const x = 42; x * 2', language: 'node' } },
+        { description: 'Run Python', params: { code: 'import sys; sys.version', language: 'python' } },
+        { description: 'Reuse a session', params: { code: 'x + 1', language: 'node', sessionId: 'existing-session-id' } },
+    ],
+    async execute(_context, params) {
+        const { code, language, sessionId } = params;
+        let session;
+        try {
+            session = getOrCreateSession(language, sessionId);
+        }
+        catch (error) {
+            return {
+                success: false,
+                output: `Failed to create REPL session: ${error instanceof Error ? error.message : String(error)}`,
+                error: {
+                    code: 'SESSION_CREATE_FAILED',
+                    message: error instanceof Error ? error.message : 'Unknown error',
+                },
+            };
+        }
+        try {
+            const output = await executeInSession(session, code);
+            // Store output in session history (capped to prevent unbounded growth)
+            session.output.push(output);
+            if (session.output.length > MAX_OUTPUT_HISTORY) {
+                session.output.splice(0, session.output.length - MAX_OUTPUT_HISTORY);
+            }
+            const result = {
+                output,
+                sessionId: session.id,
+                language,
+            };
+            return {
+                success: true,
+                data: result,
+                output: output || '(no output)',
+                sessionId: session.id,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // Remove dead session on timeout/error
+            if (error instanceof Error && error.message.includes('timed out')) {
+                sessions.delete(session.id);
+            }
+            return {
+                success: false,
+                output: `REPL execution failed: ${message}`,
+                error: {
+                    code: 'REPL_EXECUTION_FAILED',
+                    message,
+                },
+                sessionId: session.id,
+            };
+        }
+    },
+};
+// Exported helpers for testing and session management
+/** List all active REPL session IDs */
+export function listReplSessions() {
+    return Array.from(sessions.keys());
+}
+/** Terminate and remove a session by ID */
+export function closeReplSession(id) {
+    const session = sessions.get(id);
+    if (!session)
+        return false;
+    try {
+        session.process.kill('SIGTERM');
+    }
+    catch {
+        // already dead
+    }
+    sessions.delete(id);
+    return true;
+}
+/** Exposed for tests — direct access to the internal session map */
+export function getReplSessionsMap() {
+    return sessions;
+}
+//# sourceMappingURL=repl-tool.js.map

package/dist/chat/execution/tools/sessions-send.d.ts

@@ -18,15 +18,15 @@ declare const SessionsSendParamsSchema: z.ZodObject<{
     sessionId: string;
     waitForResponse: boolean;
     model?: string | undefined;
-    temperature?: number | undefined;
     maxTokens?: number | undefined;
+    temperature?: number | undefined;
 }, {
     message: string;
     sessionId: string;
     model?: string | undefined;
+    maxTokens?: number | undefined;
     waitForResponse?: boolean | undefined;
     temperature?: number | undefined;
-    maxTokens?: number | undefined;
 }>;
 export type SessionsSendParams = z.infer<typeof SessionsSendParamsSchema>;
 export interface SessionsSendResult {

package/dist/chat/execution/tools/slack-actions.d.ts

@@ -51,12 +51,12 @@ declare const SlackActionsParamsSchema: z.ZodDiscriminatedUnion<"action", [z.Zod
     topic: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     action: "set_topic";
-    topic: string;
     channel: string;
+    topic: string;
 }, {
     action: "set_topic";
-    topic: string;
     channel: string;
+    topic: string;
 }>, z.ZodObject<{
     action: z.ZodLiteral<"invite_user">;
     channel: z.ZodString;

package/dist/chat/execution/tools/system.d.ts

@@ -18,9 +18,9 @@ declare const EnvParamsSchema: z.ZodObject<{
 declare const SystemInfoParamsSchema: z.ZodObject<{
     type: z.ZodDefault<z.ZodEnum<["all", "cpu", "memory", "network", "disk", "os"]>>;
 }, "strip", z.ZodTypeAny, {
-    type: "all" | "memory" | "os" | "network" | "cpu" | "disk";
+    type: "all" | "memory" | "disk" | "network" | "cpu" | "os";
 }, {
-    type?: "all" | "memory" | "os" | "network" | "cpu" | "disk" | undefined;
+    type?: "all" | "memory" | "disk" | "network" | "cpu" | "os" | undefined;
 }>;
 declare const ProcessListParamsSchema: z.ZodObject<{
     filter: z.ZodOptional<z.ZodString>;
@@ -28,12 +28,12 @@ declare const ProcessListParamsSchema: z.ZodObject<{
     sortBy: z.ZodDefault<z.ZodOptional<z.ZodEnum<["cpu", "memory", "pid", "name"]>>>;
 }, "strip", z.ZodTypeAny, {
     limit: number;
-    sortBy: "name" | "memory" | "pid" | "cpu";
+    sortBy: "name" | "pid" | "memory" | "cpu";
     filter?: string | undefined;
 }, {
     filter?: string | undefined;
     limit?: number | undefined;
-    sortBy?: "name" | "memory" | "pid" | "cpu" | undefined;
+    sortBy?: "name" | "pid" | "memory" | "cpu" | undefined;
 }>;
 declare const PathInfoParamsSchema: z.ZodObject<{
     path: z.ZodString;

package/dist/chat/execution/tools/todo-tool.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Todo Tools
+ *
+ * Session-scoped todo list management for agents working through multi-step tasks.
+ * Stored in module-level Maps keyed by conversationId so each conversation
+ * has its own isolated list.
+ */
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+export type TodoStatus = 'pending' | 'in_progress' | 'completed' | 'blocked';
+export type TodoPriority = 'high' | 'medium' | 'low';
+export interface TodoItem {
+    id: string;
+    description: string;
+    status: TodoStatus;
+    priority?: TodoPriority;
+}
+export interface TodoWriteResult {
+    count: number;
+    summary: string;
+    items: TodoItem[];
+}
+export interface TodoReadResult {
+    count: number;
+    items: TodoItem[];
+    summary: string;
+}
+declare const TodoWriteParamsSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        status: z.ZodEnum<["pending", "in_progress", "completed", "blocked"]>;
+        priority: z.ZodOptional<z.ZodEnum<["high", "medium", "low"]>>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        status: "pending" | "in_progress" | "completed" | "blocked";
+        id: string;
+        priority?: "medium" | "low" | "high" | undefined;
+    }, {
+        description: string;
+        status: "pending" | "in_progress" | "completed" | "blocked";
+        id: string;
+        priority?: "medium" | "low" | "high" | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    items: {
+        description: string;
+        status: "pending" | "in_progress" | "completed" | "blocked";
+        id: string;
+        priority?: "medium" | "low" | "high" | undefined;
+    }[];
+}, {
+    items: {
+        description: string;
+        status: "pending" | "in_progress" | "completed" | "blocked";
+        id: string;
+        priority?: "medium" | "low" | "high" | undefined;
+    }[];
+}>;
+declare const TodoReadParamsSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export type TodoWriteParams = z.infer<typeof TodoWriteParamsSchema>;
+export type TodoReadParams = z.infer<typeof TodoReadParamsSchema>;
+export declare const todoWriteTool: ToolDefinition<TodoWriteParams, TodoWriteResult>;
+export declare const todoReadTool: ToolDefinition<TodoReadParams, TodoReadResult>;
+/** Clear todos for a given conversation key */
+export declare function clearTodos(conversationId: string): void;
+/** Get todos for a conversation key (for testing) */
+export declare function getTodos(conversationId: string): TodoItem[];
+/** Exposed for tests */
+export declare function getTodoStore(): Map<string, TodoItem[]>;
+export {};
+//# sourceMappingURL=todo-tool.d.ts.map

package/dist/chat/execution/tools/todo-tool.js

@@ -0,0 +1,152 @@
+/**
+ * Todo Tools
+ *
+ * Session-scoped todo list management for agents working through multi-step tasks.
+ * Stored in module-level Maps keyed by conversationId so each conversation
+ * has its own isolated list.
+ */
+import { z } from 'zod';
+// Module-level store: conversationId -> TodoItem[]
+const todoStore = new Map();
+// Helpers
+function getStoreKey(context) {
+    return context.conversationId;
+}
+function formatSummary(items) {
+    if (items.length === 0)
+        return 'No todos.';
+    const counts = {
+        pending: 0,
+        in_progress: 0,
+        completed: 0,
+        blocked: 0,
+    };
+    for (const item of items) {
+        counts[item.status]++;
+    }
+    const parts = [];
+    if (counts.pending > 0)
+        parts.push(`${counts.pending} pending`);
+    if (counts.in_progress > 0)
+        parts.push(`${counts.in_progress} in progress`);
+    if (counts.completed > 0)
+        parts.push(`${counts.completed} completed`);
+    if (counts.blocked > 0)
+        parts.push(`${counts.blocked} blocked`);
+    return parts.join(', ');
+}
+function renderItemsText(items) {
+    if (items.length === 0)
+        return 'No todos.';
+    return items
+        .map((item) => {
+        const statusIcon = item.status === 'completed'
+            ? '[x]'
+            : item.status === 'in_progress'
+                ? '[~]'
+                : item.status === 'blocked'
+                    ? '[!]'
+                    : '[ ]';
+        const priorityTag = item.priority ? ` (${item.priority})` : '';
+        return `${statusIcon} [${item.id}] ${item.description}${priorityTag}`;
+    })
+        .join('\n');
+}
+// Schemas
+const TodoItemSchema = z.object({
+    id: z.string().min(1).describe('Unique identifier for the todo item'),
+    description: z.string().min(1).describe('Description of the work to do'),
+    status: z.enum(['pending', 'in_progress', 'completed', 'blocked']).describe('Current status'),
+    priority: z.enum(['high', 'medium', 'low']).optional().describe('Priority level'),
+});
+const TodoWriteParamsSchema = z.object({
+    items: z.array(TodoItemSchema).min(1).describe('Full todo list to write (replaces existing list)'),
+});
+const TodoReadParamsSchema = z.object({});
+// todo_write Tool
+export const todoWriteTool = {
+    name: 'todo_write',
+    description: `Create or update a structured todo list to track multi-step work. The todo list persists for the session and helps coordinate complex tasks.
+
+Pass the complete desired list on every call — this replaces the existing list. To update an item's status, include all items with the updated status values.
+
+Status values:
+- pending: not started
+- in_progress: actively being worked on (use for at most one item at a time)
+- completed: done
+- blocked: waiting on something
+
+Use todo_read to retrieve the current list without modifying it.`,
+    category: 'profclaw',
+    securityLevel: 'safe',
+    parameters: TodoWriteParamsSchema,
+    examples: [
+        {
+            description: 'Create a todo list',
+            params: {
+                items: [
+                    { id: '1', description: 'Read existing code', status: 'completed', priority: 'high' },
+                    { id: '2', description: 'Write new feature', status: 'in_progress', priority: 'high' },
+                    { id: '3', description: 'Write tests', status: 'pending', priority: 'medium' },
+                ],
+            },
+        },
+    ],
+    async execute(context, params) {
+        const key = getStoreKey(context);
+        todoStore.set(key, params.items);
+        const summary = formatSummary(params.items);
+        const result = {
+            count: params.items.length,
+            summary,
+            items: params.items,
+        };
+        return {
+            success: true,
+            data: result,
+            output: `Todo list updated (${params.items.length} items: ${summary})\n\n${renderItemsText(params.items)}`,
+        };
+    },
+};
+// todo_read Tool
+export const todoReadTool = {
+    name: 'todo_read',
+    description: 'Read the current todo list for this session. Returns all items with their current status.',
+    category: 'profclaw',
+    securityLevel: 'safe',
+    parameters: TodoReadParamsSchema,
+    examples: [
+        { description: 'Check current todos', params: {} },
+    ],
+    async execute(context, _params) {
+        const key = getStoreKey(context);
+        const items = todoStore.get(key) ?? [];
+        const summary = formatSummary(items);
+        const result = {
+            count: items.length,
+            items,
+            summary,
+        };
+        return {
+            success: true,
+            data: result,
+            output: items.length === 0
+                ? 'No todos.'
+                : `Todo list (${items.length} items: ${summary})\n\n${renderItemsText(items)}`,
+        };
+    },
+};
+// Exported helpers for testing
+/** Clear todos for a given conversation key */
+export function clearTodos(conversationId) {
+    todoStore.delete(conversationId);
+}
+/** Get todos for a conversation key (for testing) */
+export function getTodos(conversationId) {
+    return todoStore.get(conversationId) ?? [];
+}
+/** Exposed for tests */
+export function getTodoStore() {
+    return todoStore;
+}
+//# sourceMappingURL=todo-tool.js.map

package/dist/chat/execution/tools/tool-search.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Tool Search Tool
+ *
+ * Allows the AI agent to discover available tool categories and
+ * dynamically load them into the current session.
+ *
+ * This solves the cold-start problem: instead of including all tool
+ * schemas up front (high token cost), only core tools are loaded by
+ * default, and the agent can search/load others as needed.
+ */
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+import { ToolLoader } from '../../../agents/tool-loader.js';
+declare const ToolSearchParamsSchema: z.ZodObject<{
+    query: z.ZodString;
+    autoLoad: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    autoLoad: boolean;
+}, {
+    query: string;
+    autoLoad?: boolean | undefined;
+}>;
+export type ToolSearchParams = z.infer<typeof ToolSearchParamsSchema>;
+interface ToolSearchMatch {
+    categoryName: string;
+    description: string;
+    keywords: string[];
+    tools: string[];
+    alwaysLoaded: boolean;
+    loaded: boolean;
+}
+interface ToolSearchResult {
+    query: string;
+    matches: ToolSearchMatch[];
+    autoLoaded: string | null;
+    hint: string;
+}
+/**
+ * Remove the loader for a conversation when it ends (called externally).
+ */
+export declare function clearSessionLoader(conversationId: string): void;
+/**
+ * Expose the loader for a conversation so callers (e.g. the orchestrator)
+ * can query which tools are currently loaded.
+ */
+export declare function getSessionLoader(conversationId: string): ToolLoader | undefined;
+export declare const searchAvailableToolsTool: ToolDefinition<ToolSearchParams, ToolSearchResult>;
+export {};
+//# sourceMappingURL=tool-search.d.ts.map