profclaw 0.0.1-beta.1

package/dist/agents/stop-conditions.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Agent Stop Conditions
+ *
+ * Functions that determine when an agent should stop execution.
+ * Modeled after Vercel AI SDK v5.0 stopWhen API patterns.
+ */
+import type { AgentState, StopCondition } from './types.js';
+/**
+ * Stop when step count reaches a specific number.
+ * This is the safety limit to prevent runaway agents.
+ */
+export declare function stepCountIs(maxSteps: number): StopCondition;
+/**
+ * Stop when step count exceeds a threshold.
+ */
+export declare function stepCountExceeds(threshold: number): StopCondition;
+/**
+ * Stop when a specific tool has been called.
+ */
+export declare function hasToolCall(toolName: string): StopCondition;
+/**
+ * Stop when any of the specified tools has been called.
+ */
+export declare function hasAnyToolCall(toolNames: string[]): StopCondition;
+/**
+ * Stop when a specific tool has been called N times.
+ */
+export declare function toolCallCount(toolName: string, count: number): StopCondition;
+/**
+ * Stop when total tool calls exceed a limit.
+ */
+export declare function totalToolCalls(maxCalls: number): StopCondition;
+/**
+ * Stop when token budget is exceeded.
+ */
+export declare function budgetExceeded(): StopCondition;
+/**
+ * Stop when remaining budget is below a threshold.
+ */
+export declare function budgetBelowThreshold(threshold: number): StopCondition;
+/**
+ * Stop when budget usage percentage exceeds a limit.
+ */
+export declare function budgetPercentageExceeds(percentage: number): StopCondition;
+/**
+ * Stop when the complete_task tool has been called successfully.
+ * This is the primary way for the agent to signal task completion.
+ */
+export declare function taskCompleted(): StopCondition;
+/**
+ * Stop when the model's response indicates completion.
+ * Checks the last result for done/complete flags.
+ */
+export declare function modelIndicatesCompletion(): StopCondition;
+/**
+ * Stop when no tool calls are made in the last step AND the agent has never
+ * executed any tools. This handles simple text-only responses (e.g. "hello")
+ * without prematurely killing multi-step workflows where the AI pauses to
+ * think between tool calls.
+ */
+export declare function noToolCallsInLastStep(): StopCondition;
+/**
+ * Stop when the same tool is called with the same arguments repeatedly.
+ * Prevents infinite loops where the AI keeps retrying a failing tool.
+ */
+export declare function sameToolRepeated(maxRepeats?: number): StopCondition;
+/**
+ * Stop when a tool call fails.
+ */
+export declare function toolCallFailed(): StopCondition;
+/**
+ * Stop when multiple tool calls have failed.
+ */
+export declare function consecutiveFailures(count: number): StopCondition;
+/**
+ * Stop when execution time exceeds a limit.
+ */
+export declare function timeoutExceeded(timeoutMs: number): StopCondition;
+/**
+ * Stop when ANY of the provided conditions are met (OR logic).
+ */
+export declare function anyOf(conditions: StopCondition[]): StopCondition;
+/**
+ * Stop when ALL of the provided conditions are met (AND logic).
+ */
+export declare function allOf(conditions: StopCondition[]): StopCondition;
+/**
+ * Negate a condition.
+ */
+export declare function not(condition: StopCondition): StopCondition;
+/**
+ * Create a custom stop condition with a check function.
+ */
+export declare function custom(name: string, check: (state: AgentState, lastResult: unknown) => boolean | Promise<boolean>): StopCondition;
+/**
+ * Default stop conditions for profClaw agents.
+ * These provide safety limits while allowing task completion.
+ */
+export declare const defaultStopConditions: StopCondition[];
+/**
+ * Minimal stop conditions for simple tasks.
+ */
+export declare const minimalStopConditions: StopCondition[];
+/**
+ * Strict stop conditions for budget-sensitive operations.
+ */
+export declare const strictStopConditions: StopCondition[];
+//# sourceMappingURL=stop-conditions.d.ts.map

package/dist/agents/stop-conditions.js

@@ -0,0 +1,299 @@
+/**
+ * Agent Stop Conditions
+ *
+ * Functions that determine when an agent should stop execution.
+ * Modeled after Vercel AI SDK v5.0 stopWhen API patterns.
+ */
+// Step Count Conditions
+/**
+ * Stop when step count reaches a specific number.
+ * This is the safety limit to prevent runaway agents.
+ */
+export function stepCountIs(maxSteps) {
+    return {
+        name: `stepCount:${maxSteps}`,
+        check: (state) => state.currentStep >= maxSteps,
+    };
+}
+/**
+ * Stop when step count exceeds a threshold.
+ */
+export function stepCountExceeds(threshold) {
+    return {
+        name: `stepCountExceeds:${threshold}`,
+        check: (state) => state.currentStep > threshold,
+    };
+}
+// Tool Call Conditions
+/**
+ * Stop when a specific tool has been called.
+ */
+export function hasToolCall(toolName) {
+    return {
+        name: `hasToolCall:${toolName}`,
+        check: (state) => state.toolCallHistory.some((t) => t.name === toolName && t.status === 'executed'),
+    };
+}
+/**
+ * Stop when any of the specified tools has been called.
+ */
+export function hasAnyToolCall(toolNames) {
+    return {
+        name: `hasAnyToolCall:${toolNames.join(',')}`,
+        check: (state) => state.toolCallHistory.some((t) => toolNames.includes(t.name) && t.status === 'executed'),
+    };
+}
+/**
+ * Stop when a specific tool has been called N times.
+ */
+export function toolCallCount(toolName, count) {
+    return {
+        name: `toolCallCount:${toolName}:${count}`,
+        check: (state) => {
+            const calls = state.toolCallHistory.filter((t) => t.name === toolName && t.status === 'executed');
+            return calls.length >= count;
+        },
+    };
+}
+/**
+ * Stop when total tool calls exceed a limit.
+ */
+export function totalToolCalls(maxCalls) {
+    return {
+        name: `totalToolCalls:${maxCalls}`,
+        check: (state) => state.toolCallHistory.filter((t) => t.status === 'executed').length >= maxCalls,
+    };
+}
+// Budget Conditions
+/**
+ * Stop when token budget is exceeded.
+ */
+export function budgetExceeded() {
+    return {
+        name: 'budgetExceeded',
+        check: (state) => state.usedBudget >= state.maxBudget,
+    };
+}
+/**
+ * Stop when remaining budget is below a threshold.
+ */
+export function budgetBelowThreshold(threshold) {
+    return {
+        name: `budgetBelowThreshold:${threshold}`,
+        check: (state) => state.maxBudget - state.usedBudget < threshold,
+    };
+}
+/**
+ * Stop when budget usage percentage exceeds a limit.
+ */
+export function budgetPercentageExceeds(percentage) {
+    return {
+        name: `budgetPercentage:${percentage}`,
+        check: (state) => {
+            const usagePercent = (state.usedBudget / state.maxBudget) * 100;
+            return usagePercent >= percentage;
+        },
+    };
+}
+// Task Completion Conditions
+/**
+ * Stop when the complete_task tool has been called successfully.
+ * This is the primary way for the agent to signal task completion.
+ */
+export function taskCompleted() {
+    return {
+        name: 'taskCompleted',
+        check: (state) => {
+            // Check if complete_task was called and executed successfully
+            return state.toolCallHistory.some((t) => t.name === 'complete_task' &&
+                t.status === 'executed' &&
+                t.result &&
+                typeof t.result === 'object' &&
+                t.result.complete === true);
+        },
+    };
+}
+/**
+ * Stop when the model's response indicates completion.
+ * Checks the last result for done/complete flags.
+ */
+export function modelIndicatesCompletion() {
+    return {
+        name: 'modelIndicatesCompletion',
+        check: (_state, lastResult) => {
+            if (typeof lastResult === 'object' && lastResult !== null) {
+                const result = lastResult;
+                return result.done === true || result.complete === true || result.finished === true;
+            }
+            return false;
+        },
+    };
+}
+/**
+ * Stop when no tool calls are made in the last step AND the agent has never
+ * executed any tools. This handles simple text-only responses (e.g. "hello")
+ * without prematurely killing multi-step workflows where the AI pauses to
+ * think between tool calls.
+ */
+export function noToolCallsInLastStep() {
+    return {
+        name: 'noToolCallsInLastStep',
+        check: (state, lastResult) => {
+            // If tools have been executed previously, the agent is mid-workflow —
+            // don't stop just because the current step has no tool calls.
+            if (state.toolCallHistory.some((t) => t.status === 'executed')) {
+                return false;
+            }
+            // No tools ever executed — check if this step also has none
+            if (typeof lastResult === 'object' && lastResult !== null) {
+                const result = lastResult;
+                if (result.steps && result.steps.length > 0) {
+                    const lastStep = result.steps[result.steps.length - 1];
+                    return !lastStep.toolCalls || lastStep.toolCalls.length === 0;
+                }
+            }
+            return false;
+        },
+    };
+}
+// Repeat Detection
+/**
+ * Stop when the same tool is called with the same arguments repeatedly.
+ * Prevents infinite loops where the AI keeps retrying a failing tool.
+ */
+export function sameToolRepeated(maxRepeats = 3) {
+    return {
+        name: `sameToolRepeated:${maxRepeats}`,
+        check: (state) => {
+            const history = state.toolCallHistory;
+            if (history.length < maxRepeats)
+                return false;
+            // Check the last N entries
+            const lastN = history.slice(-maxRepeats);
+            const firstName = lastN[0].name;
+            const firstArgs = JSON.stringify(lastN[0].args);
+            return lastN.every((t) => t.name === firstName && JSON.stringify(t.args) === firstArgs);
+        },
+    };
+}
+// Error Conditions
+/**
+ * Stop when a tool call fails.
+ */
+export function toolCallFailed() {
+    return {
+        name: 'toolCallFailed',
+        check: (state) => state.toolCallHistory.some((t) => t.status === 'failed'),
+    };
+}
+/**
+ * Stop when multiple tool calls have failed.
+ */
+export function consecutiveFailures(count) {
+    return {
+        name: `consecutiveFailures:${count}`,
+        check: (state) => {
+            const history = state.toolCallHistory;
+            if (history.length < count)
+                return false;
+            // Check last N calls
+            const lastN = history.slice(-count);
+            return lastN.every((t) => t.status === 'failed');
+        },
+    };
+}
+// Time Conditions
+/**
+ * Stop when execution time exceeds a limit.
+ */
+export function timeoutExceeded(timeoutMs) {
+    return {
+        name: `timeout:${timeoutMs}ms`,
+        check: (state) => Date.now() - state.createdAt >= timeoutMs,
+    };
+}
+// Composite Conditions
+/**
+ * Stop when ANY of the provided conditions are met (OR logic).
+ */
+export function anyOf(conditions) {
+    return {
+        name: `anyOf:[${conditions.map((c) => c.name).join(',')}]`,
+        check: async (state, lastResult) => {
+            for (const condition of conditions) {
+                if (await condition.check(state, lastResult)) {
+                    return true;
+                }
+            }
+            return false;
+        },
+    };
+}
+/**
+ * Stop when ALL of the provided conditions are met (AND logic).
+ */
+export function allOf(conditions) {
+    return {
+        name: `allOf:[${conditions.map((c) => c.name).join(',')}]`,
+        check: async (state, lastResult) => {
+            for (const condition of conditions) {
+                if (!(await condition.check(state, lastResult))) {
+                    return false;
+                }
+            }
+            return true;
+        },
+    };
+}
+/**
+ * Negate a condition.
+ */
+export function not(condition) {
+    return {
+        name: `not:${condition.name}`,
+        check: async (state, lastResult) => !(await condition.check(state, lastResult)),
+    };
+}
+// Custom Condition Builder
+/**
+ * Create a custom stop condition with a check function.
+ */
+export function custom(name, check) {
+    return { name, check };
+}
+// Default Stop Conditions
+/**
+ * Default stop conditions for profClaw agents.
+ * These provide safety limits while allowing task completion.
+ */
+export const defaultStopConditions = [
+    // Safety limits
+    stepCountIs(100), // Hard limit on steps
+    budgetExceeded(), // Token budget protection
+    timeoutExceeded(5 * 60 * 1000), // 5 minute timeout
+    // Task completion - multiple ways to complete
+    taskCompleted(), // Primary completion signal via complete_task tool
+    noToolCallsInLastStep(), // Complete if AI responds without tools (simple messages)
+    // Error handling
+    consecutiveFailures(3), // Stop after 3 consecutive failures
+    sameToolRepeated(3), // Stop if same tool+args called 3 times in a row
+];
+/**
+ * Minimal stop conditions for simple tasks.
+ */
+export const minimalStopConditions = [
+    stepCountIs(20), // Lower step limit
+    taskCompleted(),
+    toolCallFailed(),
+];
+/**
+ * Strict stop conditions for budget-sensitive operations.
+ */
+export const strictStopConditions = [
+    stepCountIs(50),
+    budgetPercentageExceeds(80),
+    taskCompleted(),
+    consecutiveFailures(2),
+    timeoutExceeded(2 * 60 * 1000), // 2 minute timeout
+];
+//# sourceMappingURL=stop-conditions.js.map

package/dist/agents/types.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Agent Types and Interfaces
+ *
+ * Core type definitions for the profClaw agentic loop system.
+ * Follows patterns from OpenClaw pi-agent-core for session-based execution.
+ */
+export type AgentStatus = 'idle' | 'running' | 'waiting_approval' | 'completed' | 'failed' | 'cancelled';
+export type ToolCallStatus = 'pending' | 'approved' | 'denied' | 'executed' | 'failed';
+export interface ToolCallRecord {
+    /** Unique identifier for this tool call */
+    id: string;
+    /** Name of the tool being called */
+    name: string;
+    /** Arguments passed to the tool */
+    args: Record<string, unknown>;
+    /** Result returned from the tool (if executed) */
+    result?: unknown;
+    /** Current status of the tool call */
+    status: ToolCallStatus;
+    /** Error message if failed */
+    error?: string;
+    /** When the tool call started */
+    startedAt: number;
+    /** When the tool call completed */
+    completedAt?: number;
+    /** Duration in milliseconds */
+    durationMs?: number;
+}
+export interface AgentState {
+    /** Unique session identifier */
+    sessionId: string;
+    /** Associated conversation ID */
+    conversationId: string;
+    /** Current agent status */
+    status: AgentStatus;
+    /** The user's goal/task to accomplish */
+    goal: string;
+    /** Current step number (starts at 0) */
+    currentStep: number;
+    /** Maximum token budget */
+    maxBudget: number;
+    /** Tokens used so far */
+    usedBudget: number;
+    /** Input tokens used so far */
+    inputTokensUsed: number;
+    /** Output tokens used so far */
+    outputTokensUsed: number;
+    /** History of all tool calls */
+    toolCallHistory: ToolCallRecord[];
+    /** Tool calls waiting for approval */
+    pendingToolCalls: ToolCallRecord[];
+    /** Accumulated context from tool results */
+    context: AgentContext;
+    /** When the agent was created */
+    createdAt: number;
+    /** When the agent was last updated */
+    updatedAt: number;
+    /** Final result when completed */
+    finalResult?: AgentResult;
+}
+export interface AgentContext {
+    /** Last hint from a tool response */
+    lastHint?: string;
+    /** Available projects from list_projects */
+    availableProjects?: Array<{
+        key: string;
+        name: string;
+        id: string;
+    }>;
+    /** Tickets created during this session */
+    createdTickets?: Array<{
+        id: string;
+        key: string;
+        title: string;
+        type: string;
+    }>;
+    /** Files modified during this session */
+    modifiedFiles?: string[];
+    /** Commits created during this session */
+    commits?: Array<{
+        sha: string;
+        message: string;
+    }>;
+    /** PRs created during this session */
+    pullRequests?: Array<{
+        number: number;
+        url: string;
+        title: string;
+    }>;
+    /** Custom context data */
+    [key: string]: unknown;
+}
+export interface AgentArtifact {
+    type: 'ticket' | 'commit' | 'file' | 'pr' | 'project' | 'other';
+    id: string;
+    description?: string;
+    url?: string;
+}
+export interface AgentResult {
+    /** Whether the task was completed successfully */
+    success: boolean;
+    /** Summary of what was accomplished */
+    summary: string;
+    /** Artifacts created during execution */
+    artifacts: AgentArtifact[];
+    /** Suggested next steps */
+    nextSteps?: string[];
+    /** Why the agent stopped */
+    stopReason: string;
+    /** Total steps taken */
+    totalSteps: number;
+    /** Total tokens used */
+    totalTokens: number;
+    /** Input tokens used */
+    inputTokens?: number;
+    /** Output tokens used */
+    outputTokens?: number;
+}
+export interface StopCondition {
+    /** Name for logging/debugging */
+    name: string;
+    /** Check if this condition is met */
+    check: (state: AgentState, lastResult: unknown) => boolean | Promise<boolean>;
+}
+/** Thinking effort level for Anthropic models (Opus 4.6+) */
+export type ThinkingEffort = 'low' | 'medium' | 'high' | 'max';
+/** Map effort levels to thinking budget tokens */
+export declare const EFFORT_BUDGET_MAP: Record<ThinkingEffort, number>;
+export interface AgentConfig {
+    /** Maximum steps before forced stop (safety limit) */
+    maxSteps?: number;
+    /** Maximum token budget */
+    maxBudget?: number;
+    /** Stop conditions to check after each step */
+    stopConditions?: StopCondition[];
+    /** Security mode for tool execution */
+    securityMode?: 'deny' | 'sandbox' | 'allowlist' | 'ask' | 'full';
+    /** Timeout per step in milliseconds */
+    stepTimeoutMs?: number;
+    /** Enable streaming responses */
+    enableStreaming?: boolean;
+    /** Thinking effort level for Anthropic models (low saves cost, max for complex reasoning) */
+    effort?: ThinkingEffort;
+}
+export interface AgentEvents {
+    /** Emitted when agent starts */
+    start: [state: AgentState];
+    /** Emitted at the start of each step */
+    'step:start': [state: AgentState];
+    /** Emitted when a step completes */
+    'step:complete': [state: AgentState, result: unknown];
+    /** Emitted when a tool call is made */
+    'tool:call': [state: AgentState, toolCall: ToolCallRecord];
+    /** Emitted when a tool call completes */
+    'tool:result': [state: AgentState, toolCall: ToolCallRecord];
+    /** Emitted when waiting for approval */
+    'approval:required': [state: AgentState, toolCalls: ToolCallRecord[]];
+    /** Emitted when approval is received */
+    'approval:received': [state: AgentState, approved: boolean];
+    /** Emitted when agent completes successfully */
+    complete: [state: AgentState, reason: string];
+    /** Emitted when agent fails */
+    error: [error: Error, state: AgentState];
+    /** Emitted when agent is cancelled */
+    cancelled: [state: AgentState];
+    /** Emitted for streaming text chunks */
+    'stream:chunk': [chunk: string];
+}
+export interface StepContext {
+    /** Current step number */
+    step: number;
+    /** The user's goal */
+    goal: string;
+    /** Tools used so far */
+    toolsUsed: string[];
+    /** Result from the last tool call */
+    lastToolResult?: unknown;
+    /** Accumulated context */
+    accumulatedContext: AgentContext;
+    /** Hint for next action */
+    hint: string;
+    /** Remaining budget */
+    remainingBudget: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agents/types.js

@@ -0,0 +1,14 @@
+/**
+ * Agent Types and Interfaces
+ *
+ * Core type definitions for the profClaw agentic loop system.
+ * Follows patterns from OpenClaw pi-agent-core for session-based execution.
+ */
+/** Map effort levels to thinking budget tokens */
+export const EFFORT_BUDGET_MAP = {
+    low: 1024,
+    medium: 5000,
+    high: 12000,
+    max: 32000,
+};
+//# sourceMappingURL=types.js.map

package/dist/ai/embedding-service.d.ts

@@ -0,0 +1,96 @@
+export type EmbeddingProvider = 'openai' | 'ollama' | 'voyage' | 'gemini';
+export interface EmbeddingModelLimits {
+    maxInputTokens: number;
+    maxBatchSize: number;
+    dimensions: number;
+    rateLimit: {
+        requests: number;
+        windowMs: number;
+    };
+}
+export interface EmbeddingUsageStats {
+    provider: EmbeddingProvider;
+    model: string;
+    totalRequests: number;
+    totalTokens: number;
+    totalBatches: number;
+    errors: number;
+    lastUsed: number;
+}
+export interface StreamingEmbeddingProgress {
+    completed: number;
+    total: number;
+    chunkIndex: number;
+    totalChunks: number;
+    percentage: number;
+    error: string | null;
+}
+export declare class EmbeddingService {
+    private openai?;
+    private usageStats;
+    constructor();
+    /**
+     * Generate an embedding for a string of text
+     */
+    generateEmbedding(text: string): Promise<number[]>;
+    /**
+     * Batch embedding - process multiple texts at once
+     */
+    generateBatchEmbeddings(texts: string[]): Promise<number[][]>;
+    /**
+     * Get model limits for a specific model
+     */
+    getModelLimits(model?: string): EmbeddingModelLimits | null;
+    /**
+     * Get current active embedding model name
+     */
+    getActiveModel(): string;
+    /**
+     * Get usage statistics
+     */
+    getUsageStats(): EmbeddingUsageStats[];
+    /**
+     * Get available embedding providers
+     */
+    getAvailableProviders(): EmbeddingProvider[];
+    private generateOpenAIEmbedding;
+    private batchOpenAIEmbeddings;
+    private isVoyageConfigured;
+    private generateVoyageEmbedding;
+    private batchVoyageEmbeddings;
+    private isGeminiConfigured;
+    private generateGeminiEmbedding;
+    private batchGeminiEmbeddings;
+    /**
+     * Generate embeddings with streaming progress callback.
+     * Processes texts in chunks and calls onProgress after each chunk completes.
+     */
+    generateStreamingEmbeddings(texts: string[], onProgress: (result: StreamingEmbeddingProgress) => void, options?: {
+        chunkSize?: number;
+    }): Promise<number[][]>;
+    private trackUsage;
+}
+export interface MemoryBackend {
+    name: string;
+    store(key: string, embedding: number[], metadata: Record<string, unknown>): Promise<void>;
+    search(query: number[], limit: number, filter?: Record<string, unknown>): Promise<MemorySearchResult[]>;
+    delete(key: string): Promise<boolean>;
+    stats(): Promise<{
+        totalEntries: number;
+        sizeBytes: number;
+    }>;
+}
+export interface MemorySearchResult {
+    key: string;
+    score: number;
+    metadata: Record<string, unknown>;
+}
+export interface MemoryCitation {
+    memoryId: string;
+    sourceType: 'conversation' | 'document' | 'url' | 'file' | 'manual';
+    sourceId: string;
+    timestamp: string;
+    excerpt?: string;
+}
+export declare function getEmbeddingService(): EmbeddingService;
+//# sourceMappingURL=embedding-service.d.ts.map