profclaw 2.0.0 → 2.4.0

package/dist/agents/tool-selector.js

@@ -0,0 +1,321 @@
+/**
+ * Tool Selector
+ *
+ * Sends only the tool schemas that are likely needed on a given turn instead
+ * of every registered tool. Selection is a cheap, deterministic heuristic (no
+ * LLM call): a small core set, plus groups whose keywords appear in the user
+ * message or whose tools were used recently. The model can request more groups
+ * with the `load_tools` meta-tool.
+ *
+ * Cache stability: within a session the set of loaded groups only grows, and
+ * the output is always sorted by tool name, so the tool prefix of the prompt
+ * stays byte-identical between turns unless a new group is genuinely needed.
+ *
+ * Env:
+ *   PROFCLAW_TOOL_SELECTION           off/0/false/no disables (default on)
+ *   PROFCLAW_TOOL_SELECTION_MIN_TOOLS skip selection when the tool count is at
+ *                                     or below this number (default 12)
+ *   PROFCLAW_TOOL_SELECTION_KEEP_UNGROUPED
+ *                                     keep tools that match no group, such as
+ *                                     MCP or plugin tools (default true)
+ */
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+export const LOAD_TOOLS_NAME = 'load_tools';
+export const FETCH_RESULT_NAME = 'fetch_result';
+/** Tools that are always sent. Keep this small. */
+export const CORE_TOOL_NAMES = [
+    'read_file',
+    'write_file',
+    'edit_file',
+    'search_files',
+    'grep',
+    'exec',
+    'complete_task',
+];
+// Groups
+export const TOOL_GROUPS = [
+    {
+        name: 'git',
+        description: 'git status/diff/log/branch/stash/remote/commit, PRs',
+        tools: ['git_*', 'create_pr', 'github_pr'],
+        keywords: /\b(git|commit|branch|stash|rebase|merge|diff|pull request|pr|github|checkout|push)\b/,
+    },
+    {
+        name: 'dev',
+        description: 'run tests, lint, build, typecheck, format, REPL, project info',
+        tools: ['test_run', 'lint', 'build', 'format', 'typecheck', 'project_info', 'repl_execute'],
+        keywords: /\b(test|tests|lint|build|compile|typecheck|type check|tsc|format|prettier|eslint|repl|ci)\b/,
+    },
+    {
+        name: 'files_extra',
+        description: 'directory tree, multi-file patch, patch apply, image analysis',
+        tools: ['directory_tree', 'multi_patch', 'patch_apply', 'image_analyze'],
+        keywords: /\b(tree|directory|folder|patch|refactor|rename|image|screenshot|picture|photo)\b/,
+    },
+    {
+        name: 'web',
+        description: 'web search, fetch a URL, understand a link',
+        tools: ['web_fetch', 'web_search', 'link_understand'],
+        keywords: /(https?:\/\/|\b(web|website|url|link|search online|google|internet|news|latest|docs?|documentation|browse)\b)/,
+    },
+    {
+        name: 'browser',
+        description: 'browser automation: navigate, click, fill, screenshot',
+        tools: ['browser_*'],
+        keywords: /\b(browser|playwright|click|navigate|scrape|webpage|web page|page)\b/,
+    },
+    {
+        name: 'memory',
+        description: 'search and read long-term memory',
+        tools: ['memory_*'],
+        keywords: /\b(memory|memories|remember|recall|earlier|previous(ly)?|last time|we discussed)\b/,
+    },
+    {
+        name: 'tasks',
+        description: 'tickets, projects, todos, task decomposition',
+        tools: [
+            'create_ticket', 'update_ticket', 'get_ticket', 'list_tickets',
+            'create_project', 'list_projects', 'todo_read', 'todo_write', 'decompose_task',
+        ],
+        keywords: /\b(ticket|tickets|project|projects|todo|todos|task list|backlog|issue|decompose|plan)\b/,
+    },
+    {
+        name: 'sessions',
+        description: 'sessions, sub-agents, agent messaging',
+        tools: [
+            'sessions_*', 'list_sessions', 'spawn_session', 'send_message', 'receive_messages',
+            'agents_list', 'session_status', 'subagent_orchestrate',
+        ],
+        keywords: /\b(session|sessions|agent|agents|sub-?agent|spawn|delegate|orchestrate|parallel)\b/,
+    },
+    {
+        name: 'cron',
+        description: 'scheduled jobs: create, list, pause, trigger, delete',
+        tools: ['cron_*'],
+        keywords: /\b(cron|schedule|scheduled|recurring|every (day|hour|week|minute)|daily|hourly|timer)\b/,
+    },
+    {
+        name: 'feeds',
+        description: 'RSS/feed subscriptions and digests',
+        tools: ['feed_*'],
+        keywords: /\b(feed|feeds|rss|atom|digest|subscribe|newsletter)\b/,
+    },
+    {
+        name: 'messaging',
+        description: 'Slack, Discord, Telegram, notifications, clipboard',
+        tools: ['slack_actions', 'discord_actions', 'telegram_actions', 'notify', 'clipboard_*'],
+        keywords: /\b(slack|discord|telegram|notify|notification|clipboard|copy to|paste)\b/,
+    },
+    {
+        name: 'media',
+        description: 'image generation, text to speech, canvas',
+        tools: ['openai_image_gen', 'tts_speak', 'canvas_*'],
+        keywords: /\b(generate an? image|image generation|draw|illustrat\w*|tts|speak|speech|voice|audio|canvas|render)\b/,
+    },
+    {
+        name: 'system',
+        description: 'system info, env vars, processes, which, path info, db maintenance',
+        tools: ['system_info', 'env', 'env_vars', 'process_list', 'path_info', 'which', 'db_maintenance'],
+        keywords: /\b(system|env|environment|process|processes|cpu|memory usage|disk|port|installed|which|path|maintenance|vacuum)\b/,
+    },
+];
+// Config
+function isOff(value) {
+    return ['off', '0', 'false', 'no'].includes((value ?? '').toLowerCase());
+}
+export function isToolSelectionEnabled() {
+    return !isOff(process.env.PROFCLAW_TOOL_SELECTION);
+}
+function minToolsThreshold() {
+    const parsed = Number.parseInt(process.env.PROFCLAW_TOOL_SELECTION_MIN_TOOLS ?? '', 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 12;
+}
+function keepUngrouped() {
+    return !isOff(process.env.PROFCLAW_TOOL_SELECTION_KEEP_UNGROUPED);
+}
+// Matching helpers
+function matchesPattern(name, pattern) {
+    return pattern.endsWith('*') ? name.startsWith(pattern.slice(0, -1)) : name === pattern;
+}
+/** Group name a tool belongs to, or undefined for core/ungrouped tools. */
+export function groupOfTool(name) {
+    for (const group of TOOL_GROUPS) {
+        if (group.tools.some((p) => matchesPattern(name, p)))
+            return group.name;
+    }
+    return undefined;
+}
+function isCore(name) {
+    return CORE_TOOL_NAMES.includes(name) || name === LOAD_TOOLS_NAME || name === FETCH_RESULT_NAME;
+}
+// Session state
+export class ToolSelectorSession {
+    /** Groups loaded so far. Only ever grows, which keeps the prefix stable. */
+    loaded = new Set();
+    getLoadedGroups() {
+        return Array.from(this.loaded).sort();
+    }
+    /** Mark groups loaded. Returns the names that were valid. */
+    loadGroups(names) {
+        const valid = [];
+        for (const raw of names) {
+            const name = raw.trim().toLowerCase();
+            if (TOOL_GROUPS.some((g) => g.name === name)) {
+                this.loaded.add(name);
+                valid.push(name);
+            }
+        }
+        return valid;
+    }
+    /** Keep the group of a tool that was just executed loaded. */
+    noteToolUse(toolName) {
+        const group = groupOfTool(toolName);
+        if (group)
+            this.loaded.add(group);
+    }
+    /** Add groups whose keywords match the user message. */
+    noteMessage(message) {
+        const text = message.toLowerCase();
+        const hit = [];
+        for (const group of TOOL_GROUPS) {
+            if (group.keywords.test(text)) {
+                this.loaded.add(group.name);
+                hit.push(group.name);
+            }
+        }
+        return hit;
+    }
+    /**
+     * Select tools for this turn. Output is sorted by name and, apart from
+     * newly loaded groups, identical across calls in the same session.
+     */
+    select(all, message = '') {
+        if (!isToolSelectionEnabled() || all.length <= minToolsThreshold()) {
+            return [...all].sort(byName);
+        }
+        if (message)
+            this.noteMessage(message);
+        const keepOther = keepUngrouped();
+        const picked = all.filter((tool) => {
+            if (isCore(tool.name))
+                return true;
+            const group = groupOfTool(tool.name);
+            if (group === undefined)
+                return keepOther;
+            return this.loaded.has(group);
+        });
+        return picked.sort(byName);
+    }
+}
+function byName(a, b) {
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+// Session registry (keyed by conversation)
+const MAX_SESSIONS = 500;
+const sessions = new Map();
+export function getToolSelectorSession(sessionId) {
+    let session = sessions.get(sessionId);
+    if (!session) {
+        if (sessions.size >= MAX_SESSIONS) {
+            const oldest = sessions.keys().next().value;
+            if (oldest !== undefined)
+                sessions.delete(oldest);
+        }
+        session = new ToolSelectorSession();
+        sessions.set(sessionId, session);
+    }
+    return session;
+}
+export function resetToolSelectorSessions() {
+    sessions.clear();
+}
+// Meta tools
+const LoadToolsSchema = z.object({
+    groups: z.array(z.string()).describe('Group names to load'),
+    invoke: z
+        .object({ tool: z.string(), args: z.record(z.string(), z.unknown()).optional() })
+        .optional()
+        .describe('Optionally call one of the loaded tools right now'),
+});
+const FetchResultSchema = z.object({
+    result_id: z.string(),
+    offset: z.number().int().min(0).optional(),
+    length: z.number().int().min(1).optional(),
+});
+export function parseLoadToolsArgs(args) {
+    const parsed = LoadToolsSchema.safeParse(args);
+    return parsed.success ? parsed.data : null;
+}
+export function parseFetchResultArgs(args) {
+    const parsed = FetchResultSchema.safeParse(args);
+    return parsed.success ? parsed.data : null;
+}
+/** Stable, compact meta-tool definitions. Description text must not vary. */
+export function getMetaTools(includeFetchResult) {
+    const groupList = TOOL_GROUPS.map((g) => `${g.name} (${g.description})`).join('; ');
+    const tools = [
+        {
+            name: LOAD_TOOLS_NAME,
+            description: `Load more tool groups when you need a tool you do not have. Groups: ${groupList}. ` +
+                'Returns the tool schemas; they are available from the next turn, or use invoke to call one now.',
+            parameters: LoadToolsSchema,
+        },
+    ];
+    if (includeFetchResult) {
+        tools.push({
+            name: FETCH_RESULT_NAME,
+            description: 'Read a char range of a truncated tool result by its result_id.',
+            parameters: FetchResultSchema,
+        });
+    }
+    return tools;
+}
+// Token estimate
+/** Rough tokens for one tool schema as sent to the provider (about 4 chars per token). */
+export function estimateToolTokens(tool) {
+    let schema = '{}';
+    try {
+        schema = JSON.stringify(zodToJsonSchema(tool.parameters, { $refStrategy: 'none' }));
+    }
+    catch {
+        // fall through with an empty schema
+    }
+    return Math.ceil((tool.name.length + tool.description.length + schema.length) / 4);
+}
+export function estimateToolsTokens(tools) {
+    return tools.reduce((sum, t) => sum + estimateToolTokens(t), 0);
+}
+/** Compact JSON schema for a tool, used in load_tools results. */
+export function describeTool(tool) {
+    let parameters = {};
+    try {
+        parameters = zodToJsonSchema(tool.parameters, { $refStrategy: 'none' });
+    }
+    catch {
+        // keep empty schema
+    }
+    return { name: tool.name, description: tool.description, parameters };
+}
+/** Tools belonging to a named group, sorted by name. */
+export function toolsInGroup(all, groupName) {
+    const group = TOOL_GROUPS.find((g) => g.name === groupName);
+    if (!group)
+        return [];
+    return all.filter((t) => group.tools.some((p) => matchesPattern(t.name, p))).sort(byName);
+}
+// Request-level entry point
+/**
+ * Select tools for one agentic request and append the meta-tools. When
+ * selection is disabled the input list is returned unchanged.
+ */
+export function selectToolsForRequest(tools, sessionId, message) {
+    if (!isToolSelectionEnabled() || tools.length <= minToolsThreshold()) {
+        return [...tools];
+    }
+    const session = getToolSelectorSession(sessionId);
+    const selected = session.select(tools, message);
+    const withMeta = [...selected, ...getMetaTools(true)];
+    return withMeta.sort(byName);
+}
+//# sourceMappingURL=tool-selector.js.map

package/dist/agents/transcript.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Transcript Persistence
+ *
+ * Saves all conversations to JSONL files for searchable history and session resumption.
+ * Files are stored at .profclaw/transcripts/{sessionId}.jsonl
+ * Index is stored at .profclaw/transcripts/index.json
+ */
+import * as os from 'os';
+export interface TranscriptEntry {
+    timestamp: number;
+    sessionId: string;
+    type: 'user' | 'assistant' | 'tool_call' | 'tool_result' | 'system' | 'error';
+    content: string;
+    metadata?: {
+        toolName?: string;
+        toolCallId?: string;
+        model?: string;
+        tokensUsed?: number;
+        duration?: number;
+    };
+}
+export interface SessionMeta {
+    sessionId: string;
+    title: string;
+    startedAt: number;
+    lastActivityAt: number;
+    messageCount: number;
+    tokensUsed: number;
+    model?: string;
+}
+export declare class TranscriptStore {
+    private transcriptsDir;
+    private sessionsIndex;
+    private indexDirty;
+    private indexTimer;
+    constructor(projectRoot?: string);
+    /**
+     * Append a single entry to the session's JSONL file.
+     */
+    append(entry: TranscriptEntry): void;
+    /**
+     * Read all entries for a session from its JSONL file.
+     */
+    getSession(sessionId: string): TranscriptEntry[];
+    /**
+     * List sessions sorted by lastActivityAt descending.
+     */
+    listSessions(options?: {
+        limit?: number;
+        offset?: number;
+    }): SessionMeta[];
+    /**
+     * Full-text search across transcript entries.
+     * Returns matching entries with their session ID and line number.
+     */
+    search(query: string, options?: {
+        sessionId?: string;
+        limit?: number;
+    }): Array<{
+        entry: TranscriptEntry;
+        sessionId: string;
+        lineNumber: number;
+    }>;
+    /**
+     * Get or create session metadata. Uses firstMessage to auto-generate a title
+     * if the session doesn't yet exist.
+     */
+    getOrCreateMeta(sessionId: string, firstMessage?: string): SessionMeta;
+    /**
+     * Merge partial updates into an existing session's metadata.
+     */
+    updateMeta(sessionId: string, updates: Partial<SessionMeta>): void;
+    /**
+     * Delete a session's JSONL file and remove it from the index.
+     */
+    deleteSession(sessionId: string): void;
+    flush(): void;
+    private markIndexDirty;
+    private sessionFilePath;
+    private indexFilePath;
+    private ensureDir;
+    private loadIndex;
+    private saveIndex;
+    /**
+     * Generate a human-readable title from the first 50 chars of a message.
+     * Strips newlines, trims whitespace.
+     */
+    private generateTitle;
+}
+/**
+ * Returns the process-level singleton TranscriptStore, rooted at cwd().
+ */
+export declare function getTranscriptStore(): TranscriptStore;
+export declare function _resetTranscriptStoreSingleton(): void;
+export { os };
+//# sourceMappingURL=transcript.d.ts.map

package/dist/agents/transcript.js

@@ -0,0 +1,267 @@
+/**
+ * Transcript Persistence
+ *
+ * Saves all conversations to JSONL files for searchable history and session resumption.
+ * Files are stored at .profclaw/transcripts/{sessionId}.jsonl
+ * Index is stored at .profclaw/transcripts/index.json
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+let _instance = null;
+export class TranscriptStore {
+    transcriptsDir;
+    sessionsIndex;
+    indexDirty = false;
+    indexTimer = null;
+    constructor(projectRoot) {
+        const root = projectRoot ?? process.cwd();
+        this.transcriptsDir = path.join(root, '.profclaw', 'transcripts');
+        this.sessionsIndex = new Map();
+        this.loadIndex();
+    }
+    /**
+     * Append a single entry to the session's JSONL file.
+     */
+    append(entry) {
+        this.ensureDir();
+        const filePath = this.sessionFilePath(entry.sessionId);
+        const line = JSON.stringify(entry) + '\n';
+        try {
+            fs.appendFileSync(filePath, line, 'utf8');
+        }
+        catch (err) {
+            console.error('[TranscriptStore] Failed to append entry:', err);
+            return;
+        }
+        // Update session metadata
+        const meta = this.getOrCreateMeta(entry.sessionId);
+        meta.lastActivityAt = entry.timestamp;
+        meta.messageCount += 1;
+        if (entry.metadata?.tokensUsed) {
+            meta.tokensUsed += entry.metadata.tokensUsed;
+        }
+        if (entry.metadata?.model && !meta.model) {
+            meta.model = entry.metadata.model;
+        }
+        this.sessionsIndex.set(entry.sessionId, meta);
+        this.markIndexDirty();
+    }
+    /**
+     * Read all entries for a session from its JSONL file.
+     */
+    getSession(sessionId) {
+        const filePath = this.sessionFilePath(sessionId);
+        if (!fs.existsSync(filePath)) {
+            return [];
+        }
+        try {
+            const raw = fs.readFileSync(filePath, 'utf8');
+            const entries = [];
+            for (const line of raw.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    entries.push(JSON.parse(trimmed));
+                }
+                catch {
+                    // Skip malformed lines
+                }
+            }
+            return entries;
+        }
+        catch (err) {
+            console.error(`[TranscriptStore] Failed to read session ${sessionId}:`, err);
+            return [];
+        }
+    }
+    /**
+     * List sessions sorted by lastActivityAt descending.
+     */
+    listSessions(options) {
+        const all = Array.from(this.sessionsIndex.values()).sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+        const offset = options?.offset ?? 0;
+        const limit = options?.limit ?? all.length;
+        return all.slice(offset, offset + limit);
+    }
+    /**
+     * Full-text search across transcript entries.
+     * Returns matching entries with their session ID and line number.
+     */
+    search(query, options) {
+        const results = [];
+        const lowerQuery = query.toLowerCase();
+        const limit = options?.limit ?? 50;
+        const sessionIds = options?.sessionId
+            ? [options.sessionId]
+            : Array.from(this.sessionsIndex.keys());
+        for (const sessionId of sessionIds) {
+            if (results.length >= limit)
+                break;
+            const filePath = this.sessionFilePath(sessionId);
+            if (!fs.existsSync(filePath))
+                continue;
+            let raw;
+            try {
+                raw = fs.readFileSync(filePath, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const lines = raw.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                if (results.length >= limit)
+                    break;
+                const line = lines[i].trim();
+                if (!line)
+                    continue;
+                if (line.toLowerCase().includes(lowerQuery)) {
+                    try {
+                        const entry = JSON.parse(line);
+                        results.push({ entry, sessionId, lineNumber: i + 1 });
+                    }
+                    catch {
+                        // Skip malformed lines
+                    }
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Get or create session metadata. Uses firstMessage to auto-generate a title
+     * if the session doesn't yet exist.
+     */
+    getOrCreateMeta(sessionId, firstMessage) {
+        const existing = this.sessionsIndex.get(sessionId);
+        if (existing)
+            return existing;
+        const now = Date.now();
+        const meta = {
+            sessionId,
+            title: firstMessage ? this.generateTitle(firstMessage) : `Session ${sessionId.slice(0, 8)}`,
+            startedAt: now,
+            lastActivityAt: now,
+            messageCount: 0,
+            tokensUsed: 0,
+        };
+        this.sessionsIndex.set(sessionId, meta);
+        this.saveIndex();
+        return meta;
+    }
+    /**
+     * Merge partial updates into an existing session's metadata.
+     */
+    updateMeta(sessionId, updates) {
+        const existing = this.sessionsIndex.get(sessionId);
+        if (!existing)
+            return;
+        this.sessionsIndex.set(sessionId, { ...existing, ...updates, sessionId });
+        this.saveIndex();
+    }
+    /**
+     * Delete a session's JSONL file and remove it from the index.
+     */
+    deleteSession(sessionId) {
+        const filePath = this.sessionFilePath(sessionId);
+        if (fs.existsSync(filePath)) {
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch (err) {
+                console.error(`[TranscriptStore] Failed to delete session file ${sessionId}:`, err);
+            }
+        }
+        this.sessionsIndex.delete(sessionId);
+        this.saveIndex();
+    }
+    flush() {
+        if (this.indexTimer) {
+            clearTimeout(this.indexTimer);
+            this.indexTimer = null;
+        }
+        if (this.indexDirty) {
+            this.saveIndex();
+            this.indexDirty = false;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    markIndexDirty() {
+        this.indexDirty = true;
+        if (!this.indexTimer) {
+            this.indexTimer = setTimeout(() => {
+                this.indexTimer = null;
+                if (this.indexDirty) {
+                    this.saveIndex();
+                    this.indexDirty = false;
+                }
+            }, 1000);
+        }
+    }
+    sessionFilePath(sessionId) {
+        return path.join(this.transcriptsDir, `${sessionId}.jsonl`);
+    }
+    indexFilePath() {
+        return path.join(this.transcriptsDir, 'index.json');
+    }
+    ensureDir() {
+        if (!fs.existsSync(this.transcriptsDir)) {
+            fs.mkdirSync(this.transcriptsDir, { recursive: true });
+        }
+    }
+    loadIndex() {
+        const indexPath = this.indexFilePath();
+        if (!fs.existsSync(indexPath))
+            return;
+        try {
+            const raw = fs.readFileSync(indexPath, 'utf8');
+            const sessions = JSON.parse(raw);
+            for (const session of sessions) {
+                this.sessionsIndex.set(session.sessionId, session);
+            }
+        }
+        catch (err) {
+            console.error('[TranscriptStore] Failed to load index:', err);
+        }
+    }
+    saveIndex() {
+        this.ensureDir();
+        const indexPath = this.indexFilePath();
+        const sessions = Array.from(this.sessionsIndex.values());
+        try {
+            fs.writeFileSync(indexPath, JSON.stringify(sessions, null, 2), 'utf8');
+        }
+        catch (err) {
+            console.error('[TranscriptStore] Failed to save index:', err);
+        }
+    }
+    /**
+     * Generate a human-readable title from the first 50 chars of a message.
+     * Strips newlines, trims whitespace.
+     */
+    generateTitle(message) {
+        const cleaned = message.replace(/[\r\n\t]+/g, ' ').trim();
+        if (cleaned.length <= 50)
+            return cleaned;
+        return cleaned.slice(0, 47) + '...';
+    }
+}
+/**
+ * Returns the process-level singleton TranscriptStore, rooted at cwd().
+ */
+export function getTranscriptStore() {
+    if (!_instance) {
+        _instance = new TranscriptStore();
+    }
+    return _instance;
+}
+// Exported for test injection
+export function _resetTranscriptStoreSingleton() {
+    _instance = null;
+}
+// Re-export os for use in tests (avoids test-only imports from module internals)
+export { os };
+//# sourceMappingURL=transcript.js.map