profclaw 0.0.1-beta.1

package/dist/chat/execution/smart-prompts.js

@@ -0,0 +1,151 @@
+/**
+ * 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.
+ */
+// Tool Usage Instructions (per capability level)
+const TOOL_INSTRUCTIONS = {
+    reasoning: `You have access to tools. Use them as needed to complete the user's request.
+Chain multiple tool calls when the task requires it - don't stop after one call.
+Think about what information you need and which tools will get it most efficiently.
+If a tool fails, analyze the error and try an alternative approach.`,
+    instruction: `You have access to tools. Follow these rules:
+1. Read the tool descriptions carefully before using them.
+2. Use one tool at a time. Wait for the result before deciding the next step.
+3. If a tool fails, check the error message and try with corrected parameters.
+4. Always use "read_file" before "edit_file" or "write_file" to understand current content.
+5. Use "directory_tree" or "search_files" to find files before reading them.
+6. Report your findings clearly to the user after completing tool calls.`,
+    basic: `You have access to a few tools. Use them EXACTLY as described below.
+
+RULES:
+- Use ONLY the tools listed. Do not invent tool names.
+- Provide ALL required parameters. Check the parameter list carefully.
+- Use ONE tool per step. Wait for the result before proceeding.
+- If a tool gives an error, tell the user what went wrong.
+
+COMMON PATTERNS:
+- To find a file: use "search_files" with a filename pattern
+- To read a file: use "read_file" with the exact file path
+- To run a command: use "exec" with the command string
+- To search text: use "grep" with a search pattern
+- To check status: use "git_status" (no parameters needed)
+
+Always explain what you're doing and what the tool returned.`,
+};
+// Response Format Guidance
+const RESPONSE_FORMAT = {
+    reasoning: ``, // No format constraints for reasoning models
+    instruction: `When reporting results:
+- Summarize findings concisely
+- Include relevant code snippets or file paths
+- Suggest next steps if applicable`,
+    basic: `RESPONSE FORMAT:
+- Start with what you did
+- Show the result
+- Say what it means
+- Keep responses short and clear`,
+};
+// Few-Shot Examples (for basic/instruction models)
+const FEW_SHOT_EXAMPLES = {
+    reasoning: ``, // No examples needed
+    instruction: `Example tool usage:
+User: "What files are in the src directory?"
+Assistant: I'll check the directory structure.
+[Uses directory_tree with path="src"]
+The src directory contains: [list results]`,
+    basic: `EXAMPLES OF CORRECT TOOL USAGE:
+
+Example 1 - Reading a file:
+User: "Show me the config file"
+You: I'll read the config file.
+Tool call: read_file(path="/path/to/config.ts")
+Result: [file contents shown]
+You: Here's the config file. It contains [summary].
+
+Example 2 - Running a command:
+User: "Run the tests"
+You: I'll run the test suite.
+Tool call: exec(command="pnpm test")
+Result: [test output]
+You: Tests completed. 15 passed, 0 failed.
+
+Example 3 - Finding files:
+User: "Find the login component"
+You: I'll search for it.
+Tool call: search_files(pattern="**/login*", path="src")
+Result: [matching files]
+You: Found the login component at src/components/Login.tsx.`,
+};
+// Context Budget Guidance
+/**
+ * Estimate token count for a string (rough: 4 chars per token).
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Truncate conversation history to fit within a token budget.
+ * Keeps the most recent messages and the system prompt.
+ */
+export function truncateHistory(messages, maxTokens) {
+    let totalTokens = 0;
+    const result = [];
+    // Always keep the first message (system prompt) if present
+    const systemMsg = messages[0]?.role === 'system' ? messages[0] : undefined;
+    const nonSystem = systemMsg ? messages.slice(1) : messages;
+    if (systemMsg) {
+        totalTokens += estimateTokens(systemMsg.content);
+        result.push(systemMsg);
+    }
+    // Add messages from most recent, working backwards
+    const reversed = [...nonSystem].reverse();
+    const kept = [];
+    for (const msg of reversed) {
+        const msgTokens = estimateTokens(msg.content);
+        if (totalTokens + msgTokens > maxTokens)
+            break;
+        totalTokens += msgTokens;
+        kept.unshift(msg);
+    }
+    result.push(...kept);
+    return result;
+}
+// Main Builder
+/**
+ * Build adaptive tool usage prompt segment for the given model capability.
+ */
+export function buildToolPrompt(capability) {
+    const parts = [];
+    const instructions = TOOL_INSTRUCTIONS[capability];
+    if (instructions) {
+        parts.push(instructions);
+    }
+    const format = RESPONSE_FORMAT[capability];
+    if (format) {
+        parts.push(format);
+    }
+    const examples = FEW_SHOT_EXAMPLES[capability];
+    if (examples) {
+        parts.push(examples);
+    }
+    return parts.filter(Boolean).join('\n\n');
+}
+/**
+ * Get the recommended context window usage for history,
+ * leaving room for tool schemas and response.
+ */
+export function getHistoryBudget(contextWindow, capability) {
+    // Reserve tokens for: tool schemas + system prompt + response generation
+    const reservations = {
+        basic: 3000, // Small schema + small response buffer
+        instruction: 8000, // Medium schema + response buffer
+        reasoning: 25000, // Full schema + thinking + response
+    };
+    const reserved = reservations[capability];
+    return Math.max(1000, contextWindow - reserved);
+}
+//# sourceMappingURL=smart-prompts.js.map

package/dist/chat/execution/stream-results.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Streaming Tool Results
+ *
+ * Emits tool output incrementally as it arrives rather than buffering until
+ * completion. Integrates with ToolExecutionContext.onProgress and provides
+ * an SSE adapter for the /api/chat/stream endpoint.
+ */
+import type { ToolProgressUpdate } from './types.js';
+export interface StreamChunk {
+    type: 'stdout' | 'stderr' | 'status' | 'progress' | 'complete' | 'error';
+    content: string;
+    timestamp: number;
+    toolCallId: string;
+}
+export type StreamCallback = (chunk: StreamChunk) => void;
+/**
+ * Wraps a tool executor to stream results chunk by chunk.
+ * Uses the existing onProgress callback in ToolExecutionContext.
+ *
+ * Maintains a per-call buffer so late subscribers can catch up on already-
+ * emitted output before receiving new chunks in real time.
+ */
+export declare class ToolResultStreamer {
+    private listeners;
+    private buffers;
+    /**
+     * Subscribe to stream chunks for a specific tool call.
+     * Returns an unsubscribe function - call it when done to prevent leaks.
+     */
+    subscribe(toolCallId: string, callback: StreamCallback): () => void;
+    /**
+     * Emit a chunk to all subscribers for the chunk's toolCallId.
+     * Also appends to the replay buffer.
+     */
+    emit(chunk: StreamChunk): void;
+    /**
+     * Create a progress handler compatible with ToolExecutionContext.onProgress.
+     * Pass the returned function as `context.onProgress` when executing a tool.
+     */
+    createProgressHandler(toolCallId: string): (update: ToolProgressUpdate) => void;
+    /**
+     * Get the buffered output for a tool call.
+     * Useful for late subscribers that need the full history.
+     */
+    getBuffer(toolCallId: string): StreamChunk[];
+    /**
+     * Release all subscribers and buffered data for a tool call.
+     * Should be called once the tool call is fully done and no further chunks
+     * will be emitted.
+     */
+    cleanup(toolCallId: string): void;
+}
+/**
+ * Subscribe to tool result stream chunks and write them to a WritableStream
+ * in Server-Sent Events format for the /api/chat/stream endpoint.
+ *
+ * Each SSE event has:
+ *   event: tool-chunk
+ *   data: <JSON-encoded StreamChunk>
+ *
+ * Returns an unsubscribe function. Call it when the client disconnects or
+ * the stream ends to clean up the subscription.
+ */
+export declare function streamToSSE(streamer: ToolResultStreamer, toolCallId: string, writer: WritableStreamDefaultWriter<Uint8Array>): () => void;
+//# sourceMappingURL=stream-results.d.ts.map

package/dist/chat/execution/stream-results.js

@@ -0,0 +1,156 @@
+/**
+ * Streaming Tool Results
+ *
+ * Emits tool output incrementally as it arrives rather than buffering until
+ * completion. Integrates with ToolExecutionContext.onProgress and provides
+ * an SSE adapter for the /api/chat/stream endpoint.
+ */
+import { logger } from '../../utils/logger.js';
+// ToolResultStreamer
+/**
+ * Wraps a tool executor to stream results chunk by chunk.
+ * Uses the existing onProgress callback in ToolExecutionContext.
+ *
+ * Maintains a per-call buffer so late subscribers can catch up on already-
+ * emitted output before receiving new chunks in real time.
+ */
+export class ToolResultStreamer {
+    listeners = new Map();
+    buffers = new Map();
+    // Public API
+    /**
+     * Subscribe to stream chunks for a specific tool call.
+     * Returns an unsubscribe function - call it when done to prevent leaks.
+     */
+    subscribe(toolCallId, callback) {
+        const existing = this.listeners.get(toolCallId) ?? [];
+        this.listeners.set(toolCallId, [...existing, callback]);
+        // Replay buffered chunks to the new subscriber so they receive any output
+        // that arrived before they subscribed.
+        const buffered = this.buffers.get(toolCallId) ?? [];
+        for (const chunk of buffered) {
+            try {
+                callback(chunk);
+            }
+            catch (err) {
+                logger.warn('[StreamResults] Subscriber threw during replay', {
+                    component: 'StreamResults',
+                    toolCallId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return () => {
+            const current = this.listeners.get(toolCallId);
+            if (!current)
+                return;
+            const updated = current.filter(cb => cb !== callback);
+            if (updated.length === 0) {
+                this.listeners.delete(toolCallId);
+            }
+            else {
+                this.listeners.set(toolCallId, updated);
+            }
+        };
+    }
+    /**
+     * Emit a chunk to all subscribers for the chunk's toolCallId.
+     * Also appends to the replay buffer.
+     */
+    emit(chunk) {
+        // Buffer for late subscribers
+        const buf = this.buffers.get(chunk.toolCallId) ?? [];
+        buf.push(chunk);
+        this.buffers.set(chunk.toolCallId, buf);
+        // Deliver to active subscribers
+        const callbacks = this.listeners.get(chunk.toolCallId) ?? [];
+        for (const cb of callbacks) {
+            try {
+                cb(chunk);
+            }
+            catch (err) {
+                logger.warn('[StreamResults] Subscriber threw during emit', {
+                    component: 'StreamResults',
+                    toolCallId: chunk.toolCallId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    /**
+     * Create a progress handler compatible with ToolExecutionContext.onProgress.
+     * Pass the returned function as `context.onProgress` when executing a tool.
+     */
+    createProgressHandler(toolCallId) {
+        return (update) => {
+            let chunkType;
+            switch (update.type) {
+                case 'output':
+                    chunkType = 'stdout';
+                    break;
+                case 'status':
+                    chunkType = 'status';
+                    break;
+                case 'approval-needed':
+                    chunkType = 'status';
+                    break;
+                default:
+                    chunkType = 'progress';
+            }
+            this.emit({
+                type: chunkType,
+                content: update.content,
+                timestamp: update.timestamp,
+                toolCallId,
+            });
+        };
+    }
+    /**
+     * Get the buffered output for a tool call.
+     * Useful for late subscribers that need the full history.
+     */
+    getBuffer(toolCallId) {
+        return [...(this.buffers.get(toolCallId) ?? [])];
+    }
+    /**
+     * Release all subscribers and buffered data for a tool call.
+     * Should be called once the tool call is fully done and no further chunks
+     * will be emitted.
+     */
+    cleanup(toolCallId) {
+        this.listeners.delete(toolCallId);
+        this.buffers.delete(toolCallId);
+        logger.debug('[StreamResults] Cleaned up tool call stream', {
+            component: 'StreamResults',
+            toolCallId,
+        });
+    }
+}
+// SSE Adapter
+/**
+ * Subscribe to tool result stream chunks and write them to a WritableStream
+ * in Server-Sent Events format for the /api/chat/stream endpoint.
+ *
+ * Each SSE event has:
+ *   event: tool-chunk
+ *   data: <JSON-encoded StreamChunk>
+ *
+ * Returns an unsubscribe function. Call it when the client disconnects or
+ * the stream ends to clean up the subscription.
+ */
+export function streamToSSE(streamer, toolCallId, writer) {
+    const encoder = new TextEncoder();
+    const unsubscribe = streamer.subscribe(toolCallId, (chunk) => {
+        const payload = `event: tool-chunk\ndata: ${JSON.stringify(chunk)}\n\n`;
+        writer.write(encoder.encode(payload)).catch((err) => {
+            logger.warn('[StreamResults] SSE write failed', {
+                component: 'StreamResults',
+                toolCallId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            unsubscribe();
+        });
+    });
+    return unsubscribe;
+}
+//# sourceMappingURL=stream-results.js.map

package/dist/chat/execution/tool-router.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Model-Aware Tool Router
+ *
+ * Routes tools to AI models based on model capability:
+ * - Small/local models (7B-13B): essential tier (8-10 tools)
+ * - Medium models (30B-70B, GPT-3.5): standard tier (25-30 tools)
+ * - Large models (GPT-4, Claude, Gemini Pro): full tier (all tools)
+ *
+ * Prevents tool hallucination by not overwhelming small models with 72 tool schemas.
+ */
+import type { ToolDefinition, ToolTier, ModelCapabilityLevel } from './types.js';
+interface ModelProfile {
+    capability: ModelCapabilityLevel;
+    tier: ToolTier;
+    maxTools: number;
+    contextWindow: number;
+    toolTokenBudget: number;
+}
+interface ToolRouterConfig {
+    enabled: boolean;
+    defaultTier: ToolTier;
+    maxToolTokenPercent: number;
+    dynamicPromotion: boolean;
+}
+/**
+ * Essential tools that every model gets (core interaction tools).
+ */
+export declare const ESSENTIAL_TOOL_NAMES: Set<string>;
+/**
+ * Tools restricted to full tier only (large capable models).
+ */
+export declare const FULL_ONLY_TOOL_NAMES: Set<string>;
+/**
+ * Classify a model ID into a capability profile.
+ */
+export declare function classifyModel(modelId: string): ModelProfile;
+/**
+ * Filter tools based on model capability.
+ * Returns tools appropriate for the given model's tier.
+ */
+export declare function filterToolsForModel(tools: ToolDefinition[], modelId: string, conversationId?: string): ToolDefinition[];
+/**
+ * Filter tools by an explicit tier ceiling (for ToolFilterOptions.tier).
+ * Includes all tools at or below the given tier.
+ */
+export declare function filterToolsByTier(tools: ToolDefinition[], maxTier: ToolTier): ToolDefinition[];
+/**
+ * Promote a tool for a specific conversation (grants access above normal tier).
+ */
+export declare function promoteToolForConversation(conversationId: string, toolName: string): void;
+/**
+ * Clear promoted tools for a conversation (call on conversation end).
+ */
+export declare function clearPromotedTools(conversationId: string): void;
+/**
+ * Cleanup stale promoted tools - keeps map bounded to 1000 entries.
+ */
+export declare function cleanupPromotedTools(): void;
+/**
+ * Rough estimate: ~150 tokens per tool (name, description, params schema).
+ */
+export declare function estimateToolTokens(tools: ToolDefinition[]): number;
+/**
+ * Get tool descriptions optimised for the model's capability level.
+ */
+export declare function getCompressedDescriptions(tools: ToolDefinition[], capability: ModelCapabilityLevel): string;
+/**
+ * Configure the tool router at runtime.
+ */
+export declare function configureToolRouter(newConfig: Partial<ToolRouterConfig>): void;
+/**
+ * Get a copy of the current tool router configuration.
+ */
+export declare function getToolRouterConfig(): ToolRouterConfig;
+export {};
+//# sourceMappingURL=tool-router.d.ts.map