profclaw 0.0.1-beta.1

package/dist/mcp/tool-adapter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * MCP Tool Adapter
+ *
+ * Adapts profClaw's built-in tool registry to MCP tool format.
+ * Allows external MCP clients to invoke profClaw tools with minimal setup.
+ *
+ * Security: only 'safe' and 'moderate' tools are exposed - 'dangerous' tools
+ * are never surfaced over MCP.
+ */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolDefinition } from '../chat/execution/types.js';
+/**
+ * A single tool in MCP wire format.
+ */
+export interface MCPToolSchema {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * Metadata kept alongside the schema for internal routing.
+ */
+export interface AdaptedTool {
+    schema: MCPToolSchema;
+    /** Original tool name (without prefix) */
+    internalName: string;
+    securityLevel: ToolDefinition['securityLevel'];
+}
+/**
+ * Converts all registered profClaw tools that have securityLevel 'safe' or
+ * 'moderate' to MCP tool schemas.
+ *
+ * Tools are prefixed with `profclaw__` to avoid name collisions when mixed
+ * with other MCP servers.
+ */
+export declare function adaptToolsToMCP(): AdaptedTool[];
+/**
+ * Executes a profClaw tool invoked via an MCP call.
+ *
+ * @param toolName - MCP tool name (may include `profclaw__` prefix)
+ * @param args     - Raw arguments from the MCP client (validated before execution)
+ * @returns        - MCP CallToolResult
+ */
+export declare function handleMCPToolCall(toolName: string, args: unknown): Promise<CallToolResult>;
+//# sourceMappingURL=tool-adapter.d.ts.map

package/dist/mcp/tool-adapter.js

@@ -0,0 +1,193 @@
+/**
+ * MCP Tool Adapter
+ *
+ * Adapts profClaw's built-in tool registry to MCP tool format.
+ * Allows external MCP clients to invoke profClaw tools with minimal setup.
+ *
+ * Security: only 'safe' and 'moderate' tools are exposed - 'dangerous' tools
+ * are never surfaced over MCP.
+ */
+import { randomUUID } from 'crypto';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { getToolRegistry } from '../chat/execution/registry.js';
+import { getSessionManager } from '../chat/execution/index.js';
+import { logger } from '../utils/logger.js';
+// Constants
+const PROFCLAW_PREFIX = 'profclaw__';
+const ALLOWED_SECURITY_LEVELS = new Set(['safe', 'moderate']);
+const MCP_SECURITY_POLICY = {
+    mode: 'allowlist',
+};
+// adaptToolsToMCP
+/**
+ * Converts all registered profClaw tools that have securityLevel 'safe' or
+ * 'moderate' to MCP tool schemas.
+ *
+ * Tools are prefixed with `profclaw__` to avoid name collisions when mixed
+ * with other MCP servers.
+ */
+export function adaptToolsToMCP() {
+    const registry = getToolRegistry();
+    const allTools = registry.list();
+    const adapted = [];
+    for (const tool of allTools) {
+        if (!ALLOWED_SECURITY_LEVELS.has(tool.securityLevel)) {
+            logger.debug(`[MCPToolAdapter] Skipping tool "${tool.name}" (securityLevel="${tool.securityLevel}")`, { component: 'MCPToolAdapter' });
+            continue;
+        }
+        // Honour the optional availability check
+        if (tool.isAvailable) {
+            const availability = tool.isAvailable();
+            if (!availability.available) {
+                logger.debug(`[MCPToolAdapter] Skipping unavailable tool "${tool.name}": ${availability.reason ?? 'no reason'}`, { component: 'MCPToolAdapter' });
+                continue;
+            }
+        }
+        const schema = buildMCPSchema(tool);
+        adapted.push({
+            schema,
+            internalName: tool.name,
+            securityLevel: tool.securityLevel,
+        });
+    }
+    logger.info(`[MCPToolAdapter] Adapted ${adapted.length} tool(s) to MCP format (${allTools.length - adapted.length} skipped)`, { component: 'MCPToolAdapter' });
+    return adapted;
+}
+// handleMCPToolCall
+/**
+ * Executes a profClaw tool invoked via an MCP call.
+ *
+ * @param toolName - MCP tool name (may include `profclaw__` prefix)
+ * @param args     - Raw arguments from the MCP client (validated before execution)
+ * @returns        - MCP CallToolResult
+ */
+export async function handleMCPToolCall(toolName, args) {
+    // Strip prefix to resolve the internal tool name
+    const internalName = toolName.startsWith(PROFCLAW_PREFIX)
+        ? toolName.slice(PROFCLAW_PREFIX.length)
+        : toolName;
+    const registry = getToolRegistry();
+    const tool = registry.get(internalName);
+    if (!tool) {
+        logger.warn(`[MCPToolAdapter] Tool not found: "${internalName}"`, { component: 'MCPToolAdapter' });
+        return mcpError(`Tool not found: ${toolName}`);
+    }
+    // Refuse to execute dangerous tools regardless of how the request arrived
+    if (!ALLOWED_SECURITY_LEVELS.has(tool.securityLevel)) {
+        logger.warn(`[MCPToolAdapter] Blocked execution of dangerous tool: "${internalName}"`, { component: 'MCPToolAdapter' });
+        return mcpError(`Tool "${toolName}" is not permitted over MCP (securityLevel="${tool.securityLevel}")`);
+    }
+    // Validate args with the tool's Zod schema
+    const parseResult = tool.parameters.safeParse(args);
+    if (!parseResult.success) {
+        const issues = parseResult.error.issues
+            .map((i) => `${i.path.join('.')}: ${i.message}`)
+            .join('; ');
+        logger.warn(`[MCPToolAdapter] Validation failed for "${internalName}": ${issues}`, {
+            component: 'MCPToolAdapter',
+        });
+        return mcpError(`Invalid arguments for tool "${toolName}": ${issues}`);
+    }
+    const context = buildExecutionContext();
+    const start = Date.now();
+    try {
+        const result = await tool.execute(context, parseResult.data);
+        const durationMs = Date.now() - start;
+        logger.info(`[MCPToolAdapter] Tool "${internalName}" completed in ${durationMs}ms (success=${result.success})`, { component: 'MCPToolAdapter' });
+        if (!result.success) {
+            const message = result.error?.message ?? result.output ?? 'Tool execution failed';
+            return mcpError(message);
+        }
+        // Serialise the result to a human-readable text block. Prefer explicit
+        // output string, then JSON-serialise the data payload.
+        const text = formatToolResult(result);
+        return {
+            content: [{ type: 'text', text }],
+        };
+    }
+    catch (error) {
+        const durationMs = Date.now() - start;
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`[MCPToolAdapter] Tool "${internalName}" threw after ${durationMs}ms: ${message}`, {
+            component: 'MCPToolAdapter',
+        });
+        return mcpError(`Tool execution error: ${message}`);
+    }
+}
+// Helpers
+/**
+ * Converts a ToolDefinition to an MCPToolSchema.
+ */
+function buildMCPSchema(tool) {
+    const jsonSchema = zodToJsonSchema(tool.parameters, {
+        $refStrategy: 'none',
+        target: 'openAi',
+    });
+    return {
+        name: `${PROFCLAW_PREFIX}${tool.name}`,
+        description: buildDescription(tool),
+        inputSchema: {
+            type: 'object',
+            properties: jsonSchema.properties ?? {},
+            ...(jsonSchema.required !== undefined ? { required: jsonSchema.required } : {}),
+        },
+    };
+}
+/**
+ * Augments the tool description with security and example information.
+ */
+function buildDescription(tool) {
+    let desc = tool.description;
+    if (tool.securityLevel === 'moderate') {
+        desc += '\n\nNote: This tool may require approval depending on the operation.';
+    }
+    if (tool.examples?.length) {
+        desc += '\n\nExamples:';
+        for (const example of tool.examples.slice(0, 2)) {
+            desc += `\n- ${example.description}`;
+        }
+    }
+    return desc;
+}
+/**
+ * Builds a minimal ToolExecutionContext for MCP-originated calls.
+ */
+function buildExecutionContext() {
+    return {
+        toolCallId: randomUUID(),
+        conversationId: `mcp-${randomUUID()}`,
+        workdir: process.cwd(),
+        env: { ...process.env },
+        securityPolicy: MCP_SECURITY_POLICY,
+        sessionManager: getSessionManager(),
+    };
+}
+/**
+ * Serialises a ToolResult payload into a plain-text string for MCP.
+ */
+function formatToolResult(result) {
+    if (result.output) {
+        return result.output;
+    }
+    if (result.data !== undefined) {
+        try {
+            return typeof result.data === 'string'
+                ? result.data
+                : JSON.stringify(result.data, null, 2);
+        }
+        catch {
+            return String(result.data);
+        }
+    }
+    return 'Tool executed successfully.';
+}
+/**
+ * Wraps an error message into a MCP CallToolResult with isError=true.
+ */
+function mcpError(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+//# sourceMappingURL=tool-adapter.js.map

package/dist/memory/experience-store.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Experience Store - Cross-Conversation Memory
+ *
+ * Learns from past interactions across conversations:
+ * - Tool chains that worked before
+ * - User language/framework/tool preferences
+ * - Task solutions and error recovery patterns
+ *
+ * Phase 19, Category 5
+ */
+export type ExperienceType = 'tool_chain' | 'user_preference' | 'task_solution' | 'error_recovery';
+export interface Experience {
+    id: string;
+    /** What kind of experience */
+    type: ExperienceType;
+    /** What task/intent this solved */
+    intent: string;
+    /** The solution (tool chain, preference value, etc.) */
+    solution: unknown;
+    /** Success score 0-1 */
+    successScore: number;
+    /** Context tags for retrieval */
+    tags: string[];
+    /** Conversation ID where this was learned */
+    sourceConversationId: string;
+    /** User ID if preference-related */
+    userId?: string;
+    /** Timestamps (unix ms) */
+    createdAt: number;
+    lastUsedAt: number;
+    useCount: number;
+    /** Decay weight (1.0 = fresh, approaches 0 over time) */
+    weight: number;
+}
+export interface ToolChainExperience {
+    tools: Array<{
+        name: string;
+        params: Record<string, unknown>;
+    }>;
+    totalDurationMs: number;
+    allSucceeded: boolean;
+}
+export interface UserPreferenceExperience {
+    category: string;
+    preference: string;
+    confidence: number;
+}
+export interface ExperienceStats {
+    total: number;
+    byType: Record<string, number>;
+    avgAge: number;
+}
+/**
+ * Initialize the experiences table and indexes.
+ * Call once on startup (idempotent - uses IF NOT EXISTS).
+ */
+export declare function initExperienceStore(): Promise<void>;
+/**
+ * Record a new experience learned from a conversation.
+ * Returns the generated ID.
+ */
+export declare function recordExperience(exp: Omit<Experience, 'id' | 'createdAt' | 'lastUsedAt' | 'useCount' | 'weight'>): Promise<string>;
+/**
+ * Get a single experience by ID.
+ */
+export declare function getExperience(id: string): Promise<Experience | null>;
+/**
+ * Mark an experience as used - increments useCount and updates lastUsedAt.
+ */
+export declare function markUsed(id: string): Promise<void>;
+/**
+ * Delete an experience by ID. Returns true if deleted.
+ */
+export declare function deleteExperience(id: string): Promise<boolean>;
+export interface ListExperiencesOptions {
+    type?: ExperienceType;
+    userId?: string;
+    limit?: number;
+    offset?: number;
+    minWeight?: number;
+}
+/**
+ * List experiences with optional filters.
+ */
+export declare function listExperiences(options?: ListExperiencesOptions): Promise<{
+    experiences: Experience[];
+    total: number;
+}>;
+/**
+ * Find similar experiences by keyword overlap in intent + tag matching.
+ * Before planning a task, check if a similar task was solved before.
+ */
+export declare function findSimilarExperiences(intent: string, tags?: string[], limit?: number): Promise<Experience[]>;
+/**
+ * Track a user preference (language, framework, tool, style).
+ * If an existing preference for this user+category+value exists,
+ * increments confidence. Otherwise creates a new experience.
+ */
+export declare function trackPreference(userId: string, category: string, value: string): Promise<void>;
+/**
+ * Get all tracked preferences for a user, grouped by category.
+ */
+export declare function getUserPreferences(userId: string): Promise<Record<string, UserPreferenceExperience[]>>;
+/**
+ * Apply exponential decay to all experience weights.
+ * weight = weight * exp(-ln(2) / halfLife * daysSinceLastUsed)
+ *
+ * Recent experiences approach 1.0, old ones approach 0.
+ * Run daily via cron.
+ */
+export declare function applyDecay(halfLifeDays?: number): Promise<number>;
+/**
+ * Remove experiences whose weight has dropped below the threshold.
+ * Returns count of pruned records.
+ */
+export declare function pruneExpired(minWeight?: number): Promise<number>;
+/**
+ * Get aggregate statistics about the experience store.
+ */
+export declare function getStats(): Promise<ExperienceStats>;
+//# sourceMappingURL=experience-store.d.ts.map