profclaw 2.0.0 → 2.3.0

package/dist/agents/file-snapshots.d.ts

@@ -0,0 +1,72 @@
+/**
+ * File Snapshot Manager
+ *
+ * Captures file contents before edits so users can rewind changes.
+ * Snapshots are persisted to disk under .profclaw/snapshots/{sessionId}/
+ */
+export interface FileSnapshot {
+    path: string;
+    content: string;
+    timestamp: number;
+    turnIndex: number;
+}
+export declare class FileSnapshotManager {
+    private snapshots;
+    private sessionDir;
+    constructor(sessionId: string);
+    /**
+     * Call BEFORE writing a file.
+     * Reads current contents and stores a snapshot keyed by file path.
+     * If the file does not exist yet, the snapshot is skipped (new file creation).
+     */
+    captureBeforeEdit(filePath: string, turnIndex: number): Promise<void>;
+    /**
+     * Rewind a file to its state before a specific turn.
+     * If no turnIndex is supplied, rewinds to the most recent snapshot.
+     */
+    rewind(filePath: string, turnIndex?: number): Promise<{
+        restored: boolean;
+        path: string;
+        turnIndex: number;
+    }>;
+    /**
+     * Rewind ALL files that were modified during the given turn.
+     * Restores each file to the snapshot captured at the start of that turn
+     * (i.e. the snapshot whose turnIndex equals the supplied value).
+     */
+    rewindTurn(turnIndex: number): Promise<Array<{
+        path: string;
+        restored: boolean;
+    }>>;
+    /**
+     * List all files that have at least one snapshot.
+     */
+    getModifiedFiles(): Array<{
+        path: string;
+        snapshotCount: number;
+        lastModified: number;
+    }>;
+    /**
+     * Return the full snapshot history for a specific file.
+     */
+    getHistory(filePath: string): FileSnapshot[];
+    /**
+     * Persist snapshot index to disk.
+     */
+    save(): Promise<void>;
+    /**
+     * Load snapshot index from disk (for session resume).
+     */
+    load(): Promise<void>;
+    /**
+     * Remove the on-disk snapshot directory.
+     */
+    cleanup(): Promise<void>;
+}
+/**
+ * Returns the singleton FileSnapshotManager for this process.
+ * Pass sessionId on first call to initialise; subsequent calls without an
+ * argument return the existing instance.
+ */
+export declare function getFileSnapshotManager(sessionId?: string): FileSnapshotManager;
+//# sourceMappingURL=file-snapshots.d.ts.map

package/dist/agents/file-snapshots.js

@@ -0,0 +1,182 @@
+/**
+ * File Snapshot Manager
+ *
+ * Captures file contents before edits so users can rewind changes.
+ * Snapshots are persisted to disk under .profclaw/snapshots/{sessionId}/
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+let defaultManager = null;
+export class FileSnapshotManager {
+    snapshots;
+    sessionDir;
+    constructor(sessionId) {
+        this.snapshots = new Map();
+        this.sessionDir = path.join('.profclaw', 'snapshots', sessionId);
+    }
+    /**
+     * Call BEFORE writing a file.
+     * Reads current contents and stores a snapshot keyed by file path.
+     * If the file does not exist yet, the snapshot is skipped (new file creation).
+     */
+    async captureBeforeEdit(filePath, turnIndex) {
+        const resolved = path.resolve(filePath);
+        let content;
+        try {
+            content = await fs.readFile(resolved, 'utf-8');
+        }
+        catch {
+            // File does not exist — nothing to snapshot before creation
+            return;
+        }
+        const snapshot = {
+            path: resolved,
+            content,
+            timestamp: Date.now(),
+            turnIndex,
+        };
+        const history = this.snapshots.get(resolved) ?? [];
+        history.push(snapshot);
+        this.snapshots.set(resolved, history);
+    }
+    /**
+     * Rewind a file to its state before a specific turn.
+     * If no turnIndex is supplied, rewinds to the most recent snapshot.
+     */
+    async rewind(filePath, turnIndex) {
+        const resolved = path.resolve(filePath);
+        const history = this.snapshots.get(resolved);
+        if (!history || history.length === 0) {
+            return { restored: false, path: resolved, turnIndex: turnIndex ?? -1 };
+        }
+        let target;
+        if (turnIndex === undefined) {
+            target = history[history.length - 1];
+        }
+        else {
+            // Find the latest snapshot at or before the requested turn
+            const candidates = history.filter((s) => s.turnIndex <= turnIndex);
+            if (candidates.length === 0) {
+                return { restored: false, path: resolved, turnIndex };
+            }
+            target = candidates[candidates.length - 1];
+        }
+        await fs.mkdir(path.dirname(resolved), { recursive: true });
+        await fs.writeFile(resolved, target.content, 'utf-8');
+        return { restored: true, path: resolved, turnIndex: target.turnIndex };
+    }
+    /**
+     * Rewind ALL files that were modified during the given turn.
+     * Restores each file to the snapshot captured at the start of that turn
+     * (i.e. the snapshot whose turnIndex equals the supplied value).
+     */
+    async rewindTurn(turnIndex) {
+        const results = [];
+        for (const [filePath, history] of this.snapshots.entries()) {
+            const hadChangeInTurn = history.some((s) => s.turnIndex === turnIndex);
+            if (!hadChangeInTurn)
+                continue;
+            // Find the snapshot taken at the start of this turn (before the edit)
+            const snapshot = history.find((s) => s.turnIndex === turnIndex);
+            if (!snapshot) {
+                results.push({ path: filePath, restored: false });
+                continue;
+            }
+            try {
+                const resolved = path.resolve(filePath);
+                await fs.mkdir(path.dirname(resolved), { recursive: true });
+                await fs.writeFile(resolved, snapshot.content, 'utf-8');
+                results.push({ path: filePath, restored: true });
+            }
+            catch {
+                results.push({ path: filePath, restored: false });
+            }
+        }
+        return results;
+    }
+    /**
+     * List all files that have at least one snapshot.
+     */
+    getModifiedFiles() {
+        const result = [];
+        for (const [filePath, history] of this.snapshots.entries()) {
+            if (history.length === 0)
+                continue;
+            const lastModified = history[history.length - 1].timestamp;
+            result.push({
+                path: filePath,
+                snapshotCount: history.length,
+                lastModified,
+            });
+        }
+        return result;
+    }
+    /**
+     * Return the full snapshot history for a specific file.
+     */
+    getHistory(filePath) {
+        const resolved = path.resolve(filePath);
+        return this.snapshots.get(resolved) ?? [];
+    }
+    /**
+     * Persist snapshot index to disk.
+     */
+    async save() {
+        try {
+            await fs.mkdir(this.sessionDir, { recursive: true });
+            const indexPath = path.join(this.sessionDir, 'index.json');
+            const index = {
+                sessionId: path.basename(this.sessionDir),
+                snapshots: {},
+            };
+            for (const [filePath, history] of this.snapshots.entries()) {
+                index.snapshots[filePath] = history;
+            }
+            await fs.writeFile(indexPath, JSON.stringify(index, null, 2), 'utf-8');
+        }
+        catch {
+            // Non-fatal — snapshots still work in memory
+        }
+    }
+    /**
+     * Load snapshot index from disk (for session resume).
+     */
+    async load() {
+        try {
+            const indexPath = path.join(this.sessionDir, 'index.json');
+            const raw = await fs.readFile(indexPath, 'utf-8');
+            const index = JSON.parse(raw);
+            for (const [filePath, history] of Object.entries(index.snapshots)) {
+                this.snapshots.set(filePath, history);
+            }
+        }
+        catch {
+            // No persisted data — start fresh
+        }
+    }
+    /**
+     * Remove the on-disk snapshot directory.
+     */
+    async cleanup() {
+        try {
+            await fs.rm(this.sessionDir, { recursive: true, force: true });
+        }
+        catch {
+            // Best-effort cleanup
+        }
+        this.snapshots.clear();
+    }
+}
+/**
+ * Returns the singleton FileSnapshotManager for this process.
+ * Pass sessionId on first call to initialise; subsequent calls without an
+ * argument return the existing instance.
+ */
+export function getFileSnapshotManager(sessionId) {
+    if (!defaultManager) {
+        const id = sessionId ?? `session-${Date.now().toString(36)}`;
+        defaultManager = new FileSnapshotManager(id);
+    }
+    return defaultManager;
+}
+//# sourceMappingURL=file-snapshots.js.map

package/dist/agents/index.d.ts

@@ -6,5 +6,7 @@
 export type { AgentStatus, ToolCallStatus, ToolCallRecord, AgentState, AgentContext, AgentArtifact, AgentResult, StopCondition, AgentConfig, AgentEvents, StepContext, ThinkingEffort, } from './types.js';
 export { EFFORT_BUDGET_MAP } from './types.js';
 export { AgentExecutor, createAgent, createSimpleAgent, createComplexAgent } from './executor.js';
+export type { ToolExecuteHandler } from './executor.js';
+export type { AgentEvent } from './events.js';
 export { stepCountIs, stepCountExceeds, hasToolCall, hasAnyToolCall, toolCallCount, totalToolCalls, sameToolRepeated, budgetExceeded, budgetBelowThreshold, budgetPercentageExceeds, taskCompleted, modelIndicatesCompletion, noToolCallsInLastStep, toolCallFailed, consecutiveFailures, timeoutExceeded, anyOf, allOf, not, custom, defaultStopConditions, minimalStopConditions, strictStopConditions, } from './stop-conditions.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/agents/orchestrator.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Multi-Agent Orchestrator
+ *
+ * Enables spawning, managing, and merging results from sub-agents.
+ * Supports orchestration patterns:
+ *   - Fan-out: N parallel workers + 1 synthesizer
+ *   - Pipeline: sequential agent chain (A -> B -> C)
+ *   - Debate: 2+ agents argue, 1 judges
+ *
+ * Each sub-agent gets an isolated session with scoped tool access.
+ * Parent can set token budgets, timeouts, and tool policies per child.
+ */
+export type OrchestrationPattern = 'fan_out' | 'pipeline' | 'debate' | 'custom';
+export interface SubAgentConfig {
+    id: string;
+    name: string;
+    /** The prompt/task for this sub-agent */
+    prompt: string;
+    /** System prompt override */
+    systemPrompt?: string;
+    /** AI model to use */
+    model?: string;
+    /** Max tokens this agent can consume */
+    maxTokens?: number;
+    /** Timeout in ms (default: 300000 = 5min) */
+    timeoutMs?: number;
+    /** Which tools this agent can access (empty = all) */
+    allowedTools?: string[];
+    /** Thinking effort */
+    effort?: 'low' | 'medium' | 'high';
+}
+export interface SubAgentResult {
+    agentId: string;
+    agentName: string;
+    success: boolean;
+    output: string;
+    error?: string;
+    durationMs: number;
+    tokensUsed?: number;
+}
+export interface OrchestrationConfig {
+    /** Unique ID for this orchestration */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Which pattern to use */
+    pattern: OrchestrationPattern;
+    /** Sub-agent configurations */
+    agents: SubAgentConfig[];
+    /** For fan_out: prompt for the synthesizer that merges results */
+    synthesizerPrompt?: string;
+    /** For debate: prompt for the judge */
+    judgePrompt?: string;
+    /** For pipeline: output of agent N becomes input context for agent N+1 */
+    pipelineContext?: boolean;
+    /** Overall timeout for the entire orchestration */
+    timeoutMs?: number;
+    /** Cancel all children if any fails */
+    failFast?: boolean;
+}
+export interface OrchestrationResult {
+    id: string;
+    pattern: OrchestrationPattern;
+    success: boolean;
+    /** Individual agent results */
+    agentResults: SubAgentResult[];
+    /** Synthesized/final output */
+    finalOutput: string;
+    totalDurationMs: number;
+    totalTokens: number;
+    error?: string;
+}
+/**
+ * Execute an orchestration.
+ */
+export declare function orchestrate(config: OrchestrationConfig): Promise<OrchestrationResult>;
+/**
+ * Cancel a running orchestration.
+ */
+export declare function cancelOrchestration(id: string): boolean;
+/**
+ * List active orchestrations.
+ */
+export declare function listActiveOrchestrations(): string[];
+/**
+ * A single unit of work dispatched to a sub-agent.
+ */
+export interface SubAgentTask {
+    id: string;
+    description: string;
+    prompt: string;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    result?: string;
+    error?: string;
+    startedAt?: number;
+    completedAt?: number;
+    tokensUsed: number;
+}
+/**
+ * Configuration for AgentOrchestrator.
+ */
+export interface OrchestratorConfig {
+    /** Maximum number of sub-tasks running concurrently (default: 3). */
+    maxConcurrent: number;
+    /** Timeout per sub-task in ms (default: 300_000). */
+    timeoutMs: number;
+    model?: string;
+    provider?: string;
+}
+/**
+ * Class-based orchestrator for fan-out parallel sub-agent tasks.
+ *
+ * The caller provides an `apiCall` function that wraps the actual LLM API —
+ * following the same injected-client pattern used by ContextCompactor.
+ *
+ * Usage:
+ * ```ts
+ * const orch = getAgentOrchestrator({ maxConcurrent: 2 });
+ * const results = await orch.dispatch([
+ *   { description: 'Summarise file A', prompt: '...' },
+ *   { description: 'Summarise file B', prompt: '...' },
+ * ], myApiCall);
+ * console.log(orch.synthesize(results));
+ * ```
+ */
+export declare class AgentOrchestrator {
+    private readonly tasks;
+    private readonly config;
+    /** Number of tasks currently in the 'running' state. */
+    private running;
+    /** Cancelled task IDs — checked before executing. */
+    private readonly cancelled;
+    constructor(config?: Partial<OrchestratorConfig>);
+    /**
+     * Dispatch multiple sub-tasks in parallel, respecting `maxConcurrent`.
+     * Resolves when every task has either completed, failed, or timed out.
+     */
+    dispatch(taskDefs: Array<{
+        description: string;
+        prompt: string;
+    }>, apiCall: (prompt: string) => Promise<string>): Promise<SubAgentTask[]>;
+    /**
+     * Run a single sub-agent task with timeout and cancellation support.
+     * Mutates `task` in place and returns it.
+     */
+    runTask(task: SubAgentTask, apiCall: (prompt: string) => Promise<string>): Promise<SubAgentTask>;
+    /**
+     * Return a snapshot of all tasks tracked by this orchestrator.
+     */
+    getStatus(): SubAgentTask[];
+    /**
+     * Mark a task as cancelled.  If it is still pending it will be skipped
+     * entirely; if it is already running the next post-API-call check will
+     * mark it failed.
+     */
+    cancel(taskId: string): void;
+    /**
+     * Build a markdown summary of completed task results.
+     *
+     * ```markdown
+     * ## Task Results
+     * ### 1. Summarise file A ✓
+     * <result text>
+     * ### 2. Summarise file B ✗
+     * Error: timed out after 300000ms
+     * ```
+     */
+    synthesize(tasks: SubAgentTask[]): string;
+    /**
+     * Wait until all currently-tracked tasks have left the 'pending' or
+     * 'running' state, or until the optional `timeoutMs` elapses.
+     *
+     * Resolves with the current task snapshot once settled.
+     */
+    waitAll(timeoutMs?: number): Promise<SubAgentTask[]>;
+}
+/**
+ * Return a lazily-created singleton `AgentOrchestrator`.
+ * Pass `config` on first call to customise defaults; subsequent calls with
+ * a different config will replace the singleton.
+ */
+export declare function getAgentOrchestrator(config?: Partial<OrchestratorConfig>): AgentOrchestrator;
+//# sourceMappingURL=orchestrator.d.ts.map