profclaw 0.0.1-beta.1

package/dist/chat/execution/types.d.ts

@@ -0,0 +1,337 @@
+/**
+ * Tool Execution Types
+ *
+ * Core types for the AI tool execution system.
+ * Inspired by OpenClaw's execution model.
+ */
+import type { z } from 'zod';
+/**
+ * Security mode determines how commands are validated
+ * - deny: Block all tool execution
+ * - sandbox: Run in Docker container (isolated)
+ * - allowlist: Only pre-approved commands/patterns
+ * - ask: Require user approval for each tool call
+ * - full: No restrictions (dangerous!)
+ */
+export type SecurityMode = 'deny' | 'sandbox' | 'allowlist' | 'ask' | 'full';
+/**
+ * Security policy for tool execution
+ */
+export interface SecurityPolicy {
+    mode: SecurityMode;
+    allowlist?: AllowlistEntry[];
+    askTimeout?: number;
+    sandboxConfig?: SandboxConfig;
+    dmPairing?: DMPairingConfig;
+    channelAllowlist?: ChannelAllowlistEntry[];
+    execPolicies?: ExecApprovalPolicy[];
+    pluginAllowlist?: PluginAllowlistEntry[];
+    channelPolicies?: ChannelPolicy[];
+}
+export interface AllowlistEntry {
+    pattern: string;
+    type: 'command' | 'path' | 'url' | 'plugin';
+    description?: string;
+    addedAt: string;
+    addedBy?: string;
+}
+export interface DMPairingConfig {
+    enabled: boolean;
+    codeLength: number;
+    codeExpiryMs: number;
+    maxAttempts: number;
+    trustedSenders: string[];
+}
+export interface DMPairingSession {
+    code: string;
+    senderId: string;
+    channelProvider: string;
+    createdAt: number;
+    expiresAt: number;
+    attempts: number;
+    verified: boolean;
+}
+export interface ChannelAllowlistEntry {
+    channelId: string;
+    provider: string;
+    name?: string;
+    enabled: boolean;
+    addedAt: string;
+    addedBy?: string;
+}
+export interface ExecApprovalPolicy {
+    id: string;
+    name: string;
+    match: {
+        tools?: string[];
+        commands?: string[];
+        paths?: string[];
+        users?: string[];
+        channels?: string[];
+    };
+    action: 'allow' | 'deny' | 'ask' | 'sandbox';
+    priority: number;
+    enabled: boolean;
+}
+export interface PluginAllowlistEntry {
+    pluginId: string;
+    name: string;
+    version?: string;
+    permissions: PluginPermission[];
+    addedAt: string;
+    addedBy?: string;
+    trusted: boolean;
+}
+export type PluginPermission = 'exec' | 'filesystem' | 'network' | 'system' | 'browser' | 'memory' | 'tools';
+export interface ChannelPolicy {
+    channelId: string;
+    provider: string;
+    retryAttempts: number;
+    retryDelayMs: number;
+    timeoutMs: number;
+    maxTokens?: number;
+    rateLimit?: {
+        requests: number;
+        windowMs: number;
+    };
+}
+export type SecurityRiskLevel = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+export interface SecurityRiskAnalysis {
+    level: SecurityRiskLevel;
+    score: number;
+    factors: SecurityRiskFactor[];
+    recommendation: 'allow' | 'review' | 'deny';
+    explanation: string;
+}
+export interface SecurityRiskFactor {
+    name: string;
+    weight: number;
+    detected: boolean;
+    detail?: string;
+}
+export interface SandboxConfig {
+    enabled: boolean;
+    image: string;
+    containerName?: string;
+    workdir: string;
+    mounts?: SandboxMount[];
+    env?: Record<string, string>;
+    networkMode?: 'none' | 'bridge' | 'host';
+    memoryLimit?: string;
+    cpuLimit?: string;
+}
+export interface SandboxMount {
+    hostPath: string;
+    containerPath: string;
+    readonly?: boolean;
+}
+/**
+ * Tool definition for AI function calling
+ * Note: parameters uses z.ZodType with unknown input type to support .default() schemas
+ */
+export interface ToolDefinition<TParams = unknown, TResult = unknown> {
+    name: string;
+    description: string;
+    category: ToolCategory;
+    parameters: z.ZodType<TParams, z.ZodTypeDef, unknown>;
+    requiresApproval?: boolean;
+    securityLevel: 'safe' | 'moderate' | 'dangerous';
+    allowedHosts?: ('sandbox' | 'gateway' | 'local')[];
+    /** Tool tier for model-aware routing. Defaults to 'standard'. */
+    tier?: ToolTier;
+    execute: ToolExecutor<TParams, TResult>;
+    /**
+     * Optional availability check. If defined, the tool is only included in the
+     * tool list sent to the AI model when `available` is true. Tools that require
+     * external configuration (API keys, services) should implement this to avoid
+     * wasting tokens on tools the model can't use.
+     *
+     * Follows OpenClaw's config-gated tool pattern.
+     */
+    isAvailable?: () => ToolAvailability;
+    examples?: ToolExample[];
+    rateLimit?: RateLimitConfig;
+}
+export interface ToolAvailability {
+    available: boolean;
+    reason?: string;
+}
+export type ToolCategory = 'execution' | 'filesystem' | 'web' | 'data' | 'system' | 'profclaw' | 'memory' | 'browser' | 'custom';
+/**
+ * Tool tier determines which models receive this tool.
+ * - essential: Core tools that work reliably with any model (8-10 tools)
+ * - standard: Tools that need moderate reasoning (25-30 tools)
+ * - full: All tools, only for large/capable models (72 tools)
+ */
+export type ToolTier = 'essential' | 'standard' | 'full';
+/**
+ * Model capability level for adaptive prompting and tool selection.
+ * - basic: Small/local models (<14B params). Simple instruction following.
+ * - instruction: Medium models (14B-70B). Can follow multi-step instructions.
+ * - reasoning: Large frontier models. Chain-of-thought, complex tool orchestration.
+ */
+export type ModelCapabilityLevel = 'basic' | 'instruction' | 'reasoning';
+export interface ToolExample {
+    description: string;
+    params: Record<string, unknown>;
+    expectedOutput?: string;
+}
+export interface RateLimitConfig {
+    maxCalls: number;
+    windowMs: number;
+}
+export type ToolExecutor<TParams, TResult> = (context: ToolExecutionContext, params: TParams) => Promise<ToolResult<TResult>>;
+export interface ToolExecutionContext {
+    toolCallId: string;
+    conversationId: string;
+    userId?: string;
+    workdir: string;
+    env: Record<string, string>;
+    securityPolicy: SecurityPolicy;
+    isolationContext?: IsolationContext;
+    onProgress?: (update: ToolProgressUpdate) => void;
+    signal?: AbortSignal;
+    sessionManager: SessionManager;
+}
+/** Per-conversation isolation boundaries */
+export interface IsolationContext {
+    conversationId: string;
+    userId?: string;
+    /** Memory paths this conversation is allowed to access */
+    allowedMemoryPaths: string[];
+}
+export interface ToolProgressUpdate {
+    type: 'output' | 'status' | 'approval-needed';
+    content: string;
+    timestamp: number;
+}
+export interface ToolResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    output?: string;
+    error?: ToolError;
+    durationMs?: number;
+    sessionId?: string;
+    isRunning?: boolean;
+    isBackgrounded?: boolean;
+}
+export interface ToolError {
+    code: string;
+    message: string;
+    details?: unknown;
+    retryable?: boolean;
+}
+export interface SessionManager {
+    create(session: Omit<ToolSession, 'id' | 'createdAt'>): ToolSession;
+    get(sessionId: string): ToolSession | undefined;
+    update(sessionId: string, update: Partial<ToolSession>): void;
+    list(filter?: SessionFilter): ToolSession[];
+    kill(sessionId: string): Promise<void>;
+    cleanup(): void;
+}
+export interface ToolSession {
+    id: string;
+    toolCallId: string;
+    toolName: string;
+    conversationId: string;
+    pid?: number;
+    command?: string;
+    workdir?: string;
+    status: SessionStatus;
+    createdAt: number;
+    startedAt?: number;
+    completedAt?: number;
+    stdout: string;
+    stderr: string;
+    exitCode?: number | null;
+    exitSignal?: string | null;
+    maxOutputChars: number;
+    truncated: boolean;
+    backgrounded: boolean;
+    notifyOnExit: boolean;
+}
+export type SessionStatus = 'pending' | 'running' | 'completed' | 'failed' | 'killed' | 'timeout';
+export interface SessionFilter {
+    conversationId?: string;
+    toolName?: string;
+    status?: SessionStatus[];
+    since?: number;
+}
+export interface ApprovalRequest {
+    id: string;
+    toolCallId: string;
+    toolName: string;
+    conversationId: string;
+    command?: string;
+    params: Record<string, unknown>;
+    securityLevel: 'moderate' | 'dangerous';
+    createdAt: number;
+    expiresAt: number;
+    status: 'pending' | 'approved' | 'denied' | 'expired';
+    decision?: ApprovalDecision;
+    decidedAt?: number;
+    decidedBy?: string;
+}
+export type ApprovalDecision = 'allow-once' | 'allow-always' | 'deny';
+export interface ApprovalResponse {
+    requestId: string;
+    decision: ApprovalDecision;
+    userId?: string;
+}
+export interface AIToolCall {
+    id?: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface ToolCallResult {
+    toolCallId: string;
+    toolName: string;
+    result: ToolResult;
+    approvalRequired?: boolean;
+    approvalId?: string;
+    rateLimitInfo?: {
+        remaining: number;
+        resetAt: number;
+    };
+}
+/** Options for filtering tools when building AI schemas */
+export interface ToolFilterOptions {
+    /** Only include tools at or below this tier */
+    tier?: ToolTier;
+    /** Model capability level for description adaptation */
+    capabilityLevel?: ModelCapabilityLevel;
+    /** Maximum token budget for tool schemas (approximate) */
+    maxSchemaTokens?: number;
+    /** Specific tool names to include regardless of tier */
+    promote?: string[];
+}
+export interface ToolRegistry {
+    register<TParams, TResult>(tool: ToolDefinition<TParams, TResult>): void;
+    unregister(name: string): boolean;
+    get(name: string): ToolDefinition | undefined;
+    list(category?: ToolCategory): ToolDefinition[];
+    /** Get tools filtered by options (tier ceiling, token budget, promoted overrides). */
+    getForAI(options?: ToolFilterOptions): AIToolSchema[];
+    /**
+     * Get tools filtered for a specific model's capability tier.
+     * Preferred over getForAI() when the model ID is known - uses model classification
+     * to automatically apply the right tier (essential/standard/full).
+     */
+    getForModel(modelId: string, conversationId?: string): AIToolSchema[];
+}
+/**
+ * Tool schema for AI function calling (OpenAI/Anthropic format)
+ */
+export interface AIToolSchema {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: 'object';
+            properties: Record<string, unknown>;
+            required?: string[];
+        };
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/chat/execution/types.js

@@ -0,0 +1,8 @@
+/**
+ * Tool Execution Types
+ *
+ * Core types for the AI tool execution system.
+ * Inspired by OpenClaw's execution model.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/chat/execution/workflows/built-in.d.ts

@@ -0,0 +1,10 @@
+import type { WorkflowDefinition } from './types.js';
+/**
+ * Built-in workflow templates for common development tasks.
+ * These provide pre-built tool chains for small/local models that
+ * cannot reason about multi-step workflows on their own.
+ */
+export declare const BUILT_IN_WORKFLOWS: WorkflowDefinition[];
+/** Look up a built-in workflow by ID */
+export declare function getBuiltInWorkflow(id: string): WorkflowDefinition | undefined;
+//# sourceMappingURL=built-in.d.ts.map

package/dist/chat/execution/workflows/built-in.js

@@ -0,0 +1,249 @@
+/**
+ * Built-in workflow templates for common development tasks.
+ * These provide pre-built tool chains for small/local models that
+ * cannot reason about multi-step workflows on their own.
+ */
+export const BUILT_IN_WORKFLOWS = [
+    {
+        id: 'deploy',
+        name: 'Deploy',
+        description: 'Full deployment pipeline: check status, pull latest, build, test, and deploy.',
+        triggers: ['deploy', 'deployment', 'ship it', 'push to production', 'release', 'go live'],
+        variables: {
+            buildCommand: 'pnpm build',
+            testCommand: 'pnpm test',
+            deployCommand: 'docker compose up -d',
+            branch: 'main',
+        },
+        steps: [
+            {
+                id: 'git-status',
+                name: 'Check working tree is clean',
+                tool: 'exec',
+                params: { command: 'git status --porcelain' },
+                captureOutput: 'gitStatus',
+            },
+            {
+                id: 'git-pull',
+                name: 'Pull latest changes',
+                tool: 'exec',
+                params: { command: 'git pull origin {{branch}}' },
+                captureOutput: 'pullOutput',
+            },
+            {
+                id: 'build',
+                name: 'Build project',
+                tool: 'exec',
+                params: { command: '{{buildCommand}}' },
+                captureOutput: 'buildOutput',
+            },
+            {
+                id: 'test',
+                name: 'Run tests',
+                tool: 'exec',
+                params: { command: '{{testCommand}}' },
+                captureOutput: 'testOutput',
+                continueOnError: true,
+            },
+            {
+                id: 'deploy',
+                name: 'Deploy application',
+                tool: 'exec',
+                params: { command: '{{deployCommand}}' },
+                captureOutput: 'deployOutput',
+            },
+        ],
+    },
+    {
+        id: 'code-review',
+        name: 'Code Review',
+        description: 'Review staged changes - diff analysis and file inspection for structured review.',
+        triggers: [
+            'code review',
+            'review my changes',
+            'review staged',
+            'review diff',
+            'check my code',
+            'review pr',
+        ],
+        steps: [
+            {
+                id: 'staged-diff',
+                name: 'Get staged diff',
+                tool: 'exec',
+                params: { command: 'git diff --staged' },
+                captureOutput: 'stagedDiff',
+            },
+            {
+                id: 'changed-files',
+                name: 'List changed files',
+                tool: 'exec',
+                params: { command: 'git diff --staged --name-only' },
+                captureOutput: 'changedFiles',
+            },
+            {
+                id: 'recent-log',
+                name: 'Check recent commit history',
+                tool: 'exec',
+                params: { command: 'git log -5 --oneline' },
+                captureOutput: 'recentLog',
+            },
+        ],
+    },
+    {
+        id: 'debug',
+        name: 'Debug',
+        description: 'Systematic debugging: check recent changes, find error patterns, locate TODOs.',
+        triggers: [
+            'debug',
+            'investigate error',
+            'find the bug',
+            'why is it failing',
+            'troubleshoot',
+            'diagnose',
+        ],
+        variables: {
+            errorPattern: 'error',
+            searchDir: '.',
+        },
+        steps: [
+            {
+                id: 'recent-changes',
+                name: 'Check recent commits',
+                tool: 'exec',
+                params: { command: 'git log -5 --oneline' },
+                captureOutput: 'recentChanges',
+            },
+            {
+                id: 'find-errors',
+                name: 'Search for error pattern',
+                tool: 'search_files',
+                params: { pattern: '{{errorPattern}}', directory: '{{searchDir}}' },
+                captureOutput: 'errorMatches',
+                continueOnError: true,
+            },
+            {
+                id: 'find-todos',
+                name: 'Find TODOs and FIXMEs',
+                tool: 'exec',
+                params: { command: 'grep -rn "TODO\\|FIXME\\|HACK" {{searchDir}} --include="*.ts" --include="*.js" -l 2>/dev/null | head -20' },
+                captureOutput: 'todoFiles',
+                continueOnError: true,
+            },
+        ],
+    },
+    {
+        id: 'research',
+        name: 'Research',
+        description: 'Web research workflow: search and fetch top result for summarized findings.',
+        triggers: [
+            'research',
+            'look up',
+            'find information about',
+            'search the web for',
+            'investigate',
+            'what is',
+        ],
+        variables: {
+            query: '',
+        },
+        steps: [
+            {
+                id: 'web-search',
+                name: 'Search the web',
+                tool: 'web_search',
+                params: { query: '{{query}}' },
+                captureOutput: 'searchResults',
+            },
+            {
+                id: 'fetch-top',
+                name: 'Fetch top result',
+                tool: 'web_fetch',
+                params: { url: '{{topResultUrl}}' },
+                captureOutput: 'pageContent',
+                continueOnError: true,
+            },
+        ],
+    },
+    {
+        id: 'refactor',
+        name: 'Refactor',
+        description: 'Identify files needing refactoring based on a target pattern.',
+        triggers: [
+            'refactor',
+            'clean up',
+            'improve code',
+            'find usages of',
+            'replace all',
+            'rename',
+        ],
+        variables: {
+            targetPattern: '',
+            searchDir: 'src',
+        },
+        steps: [
+            {
+                id: 'find-pattern',
+                name: 'Find pattern occurrences',
+                tool: 'search_files',
+                params: { pattern: '{{targetPattern}}', directory: '{{searchDir}}' },
+                captureOutput: 'patternMatches',
+            },
+            {
+                id: 'list-affected',
+                name: 'List affected files',
+                tool: 'exec',
+                params: { command: 'grep -rn "{{targetPattern}}" {{searchDir}} --include="*.ts" --include="*.tsx" -l 2>/dev/null' },
+                captureOutput: 'affectedFiles',
+                continueOnError: true,
+            },
+        ],
+    },
+    {
+        id: 'test-and-fix',
+        name: 'Test and Fix',
+        description: 'Run tests, identify failures, and gather source context for fixing.',
+        triggers: [
+            'test and fix',
+            'fix failing tests',
+            'run tests and fix',
+            'tests are failing',
+            'fix tests',
+        ],
+        variables: {
+            testCommand: 'pnpm test',
+        },
+        steps: [
+            {
+                id: 'run-tests',
+                name: 'Run test suite',
+                tool: 'exec',
+                params: { command: '{{testCommand}} 2>&1' },
+                captureOutput: 'testOutput',
+                continueOnError: true,
+            },
+            {
+                id: 'find-failing',
+                name: 'Find failing test files',
+                tool: 'search_files',
+                params: { pattern: '{{failingTestPattern}}', directory: 'src' },
+                captureOutput: 'failingFiles',
+                continueOnError: true,
+                condition: '{{testOutput}} !== ""',
+            },
+            {
+                id: 'check-coverage',
+                name: 'Check test coverage summary',
+                tool: 'exec',
+                params: { command: '{{testCommand}} --coverage --reporter=text 2>&1 | tail -30' },
+                captureOutput: 'coverageOutput',
+                continueOnError: true,
+            },
+        ],
+    },
+];
+/** Look up a built-in workflow by ID */
+export function getBuiltInWorkflow(id) {
+    return BUILT_IN_WORKFLOWS.find((w) => w.id === id);
+}
+//# sourceMappingURL=built-in.js.map

package/dist/chat/execution/workflows/executor.d.ts

@@ -0,0 +1,13 @@
+import type { WorkflowDefinition, WorkflowExecutionContext, WorkflowExecuteOptions, WorkflowSummary } from './types.js';
+export declare class WorkflowExecutor {
+    /**
+     * Execute a workflow step by step, returning a summary of all results.
+     * Supports variable interpolation, conditional steps, and cancellation.
+     */
+    execute(workflow: WorkflowDefinition, context: WorkflowExecutionContext, options?: WorkflowExecuteOptions): Promise<WorkflowSummary>;
+    /** Cancel a running workflow by its execution ID */
+    cancel(executionId: string): void;
+    /** Execute a single workflow step, applying param interpolation and overrides */
+    private executeStep;
+}
+//# sourceMappingURL=executor.d.ts.map