profclaw 2.3.0 → 2.4.0

package/dist/agents/tool-selector.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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';
+export interface SelectableTool {
+    name: string;
+    description: string;
+    parameters: unknown;
+}
+export interface ToolGroup {
+    name: string;
+    description: string;
+    /** Exact tool names, or prefixes ending in `*` */
+    tools: string[];
+    /** Matched against the lowercased user message */
+    keywords: RegExp;
+}
+export declare const LOAD_TOOLS_NAME = "load_tools";
+export declare const FETCH_RESULT_NAME = "fetch_result";
+/** Tools that are always sent. Keep this small. */
+export declare const CORE_TOOL_NAMES: readonly string[];
+export declare const TOOL_GROUPS: readonly ToolGroup[];
+export declare function isToolSelectionEnabled(): boolean;
+/** Group name a tool belongs to, or undefined for core/ungrouped tools. */
+export declare function groupOfTool(name: string): string | undefined;
+export declare class ToolSelectorSession {
+    /** Groups loaded so far. Only ever grows, which keeps the prefix stable. */
+    private readonly loaded;
+    getLoadedGroups(): string[];
+    /** Mark groups loaded. Returns the names that were valid. */
+    loadGroups(names: string[]): string[];
+    /** Keep the group of a tool that was just executed loaded. */
+    noteToolUse(toolName: string): void;
+    /** Add groups whose keywords match the user message. */
+    noteMessage(message: string): string[];
+    /**
+     * Select tools for this turn. Output is sorted by name and, apart from
+     * newly loaded groups, identical across calls in the same session.
+     */
+    select<T extends SelectableTool>(all: readonly T[], message?: string): T[];
+}
+export declare function getToolSelectorSession(sessionId: string): ToolSelectorSession;
+export declare function resetToolSelectorSessions(): void;
+declare const LoadToolsSchema: z.ZodObject<{
+    groups: z.ZodArray<z.ZodString, "many">;
+    invoke: z.ZodOptional<z.ZodObject<{
+        tool: z.ZodString;
+        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        tool: string;
+        args?: Record<string, unknown> | undefined;
+    }, {
+        tool: string;
+        args?: Record<string, unknown> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    groups: string[];
+    invoke?: {
+        tool: string;
+        args?: Record<string, unknown> | undefined;
+    } | undefined;
+}, {
+    groups: string[];
+    invoke?: {
+        tool: string;
+        args?: Record<string, unknown> | undefined;
+    } | undefined;
+}>;
+declare const FetchResultSchema: z.ZodObject<{
+    result_id: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    length: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    result_id: string;
+    length?: number | undefined;
+    offset?: number | undefined;
+}, {
+    result_id: string;
+    length?: number | undefined;
+    offset?: number | undefined;
+}>;
+export type LoadToolsArgs = z.infer<typeof LoadToolsSchema>;
+export type FetchResultArgs = z.infer<typeof FetchResultSchema>;
+export declare function parseLoadToolsArgs(args: unknown): LoadToolsArgs | null;
+export declare function parseFetchResultArgs(args: unknown): FetchResultArgs | null;
+/** Stable, compact meta-tool definitions. Description text must not vary. */
+export declare function getMetaTools(includeFetchResult: boolean): SelectableTool[];
+/** Rough tokens for one tool schema as sent to the provider (about 4 chars per token). */
+export declare function estimateToolTokens(tool: SelectableTool): number;
+export declare function estimateToolsTokens(tools: readonly SelectableTool[]): number;
+/** Compact JSON schema for a tool, used in load_tools results. */
+export declare function describeTool(tool: SelectableTool): {
+    name: string;
+    description: string;
+    parameters: unknown;
+};
+/** Tools belonging to a named group, sorted by name. */
+export declare function toolsInGroup<T extends SelectableTool>(all: readonly T[], groupName: string): T[];
+/**
+ * Select tools for one agentic request and append the meta-tools. When
+ * selection is disabled the input list is returned unchanged.
+ */
+export declare function selectToolsForRequest<T extends SelectableTool>(tools: readonly T[], sessionId: string, message: string): Array<T | SelectableTool>;
+export {};
+//# sourceMappingURL=tool-selector.d.ts.map

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/verified-run-git.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Git-backed workspace for verified runs.
+ *
+ * Isolation comes from WorktreeManager. Checkpoints are commits on the run
+ * branch: restoring is `git reset --hard <sha>` plus `git clean -fd`, so a
+ * failed attempt can be discarded without touching the user's main tree.
+ * All git calls use execFile (no shell), and nothing here pushes.
+ */
+import type { FileChangeStatus } from './session-diff.js';
+export interface WorkspaceChange {
+    /** Absolute path in the workspace */
+    path: string;
+    /** Path relative to the workspace root */
+    relPath: string;
+    status: FileChangeStatus;
+    /** Content at the base commit, null for created files */
+    original: string | null;
+}
+/** Everything the run loop needs from an isolated working copy. */
+export interface RunWorkspace {
+    readonly path: string;
+    readonly branch: string;
+    /** Create the isolated copy and return a ref for its pristine state. */
+    prepare(): Promise<string>;
+    /** Persist the current state and return a ref that restore() accepts. */
+    checkpoint(label: string): Promise<string>;
+    /** Discard everything since the given ref. */
+    restore(ref: string): Promise<void>;
+    /** Files differing from the pristine state. */
+    changedFiles(): Promise<WorkspaceChange[]>;
+    /** Remove the isolated copy (the branch is kept). */
+    dispose(): Promise<void>;
+}
+export declare class GitRunWorkspace implements RunWorkspace {
+    private readonly projectRoot;
+    private readonly runId;
+    path: string;
+    branch: string;
+    private baseRef;
+    private readonly manager;
+    constructor(projectRoot: string, runId: string, branchName?: string);
+    private git;
+    prepare(): Promise<string>;
+    checkpoint(label: string): Promise<string>;
+    restore(ref: string): Promise<void>;
+    changedFiles(): Promise<WorkspaceChange[]>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=verified-run-git.d.ts.map

package/dist/agents/verified-run-git.js

@@ -0,0 +1,82 @@
+/**
+ * Git-backed workspace for verified runs.
+ *
+ * Isolation comes from WorktreeManager. Checkpoints are commits on the run
+ * branch: restoring is `git reset --hard <sha>` plus `git clean -fd`, so a
+ * failed attempt can be discarded without touching the user's main tree.
+ * All git calls use execFile (no shell), and nothing here pushes.
+ */
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { join } from 'node:path';
+import { WorktreeManager } from './worktree-manager.js';
+const execFile = promisify(execFileCb);
+const IDENTITY = ['-c', 'user.name=profClaw', '-c', 'user.email=bot@profclaw.ai', '-c', 'commit.gpgsign=false'];
+export class GitRunWorkspace {
+    projectRoot;
+    runId;
+    path = '';
+    branch;
+    baseRef = '';
+    manager;
+    constructor(projectRoot, runId, branchName) {
+        this.projectRoot = projectRoot;
+        this.runId = runId;
+        this.manager = new WorktreeManager(projectRoot);
+        this.branch = branchName ?? `profclaw/run-${runId}`;
+    }
+    async git(args, cwd) {
+        const { stdout } = await execFile('git', args, {
+            cwd: cwd ?? (this.path || this.projectRoot),
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    async prepare() {
+        const info = await this.manager.create({
+            taskId: this.runId,
+            branchName: this.branch,
+        });
+        this.path = info.path;
+        this.branch = info.branch;
+        this.baseRef = (await this.git(['rev-parse', 'HEAD'])).trim();
+        return this.baseRef;
+    }
+    async checkpoint(label) {
+        await this.git(['add', '-A']);
+        await this.git([...IDENTITY, 'commit', '--allow-empty', '--no-verify', '-m', `profclaw run: ${label}`]);
+        return (await this.git(['rev-parse', 'HEAD'])).trim();
+    }
+    async restore(ref) {
+        await this.git(['reset', '--hard', ref]);
+        await this.git(['clean', '-fd']);
+    }
+    async changedFiles() {
+        // Include uncommitted work by staging it into the index first (no commit).
+        await this.git(['add', '-A']);
+        const raw = await this.git(['diff', '--cached', '--name-status', '--no-renames', this.baseRef]);
+        const changes = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            const [code, ...rest] = line.split('\t');
+            const relPath = rest.join('\t');
+            const status = code === 'A' ? 'created' : code === 'D' ? 'deleted' : 'modified';
+            let original = null;
+            if (status !== 'created') {
+                try {
+                    original = await this.git(['show', `${this.baseRef}:${relPath}`]);
+                }
+                catch {
+                    original = null;
+                }
+            }
+            changes.push({ path: join(this.path, relPath), relPath, status, original });
+        }
+        return changes;
+    }
+    async dispose() {
+        await this.manager.remove(this.runId);
+    }
+}
+//# sourceMappingURL=verified-run-git.js.map