@helmiq/crew 0.1.0

package/dist/engine/tool-dispatch.js

@@ -0,0 +1,146 @@
+/**
+ * Runtime-managed tool-call dispatch loop per ADR-0010.
+ *
+ * Calls the provider with schema-only tools, intercepts ToolCallRecord
+ * results, dispatches each to the corresponding CrewTool execute function,
+ * appends tool-result messages, and repeats until the LLM produces a
+ * final text response or the max round limit is reached.
+ */
+import { callLlm } from './llm-client.js';
+import { expandToolNames } from '../tools/tool-groups.js';
+const DEFAULT_MAX_ROUNDS = 8;
+export function toSchemaOnlyToolSet(tools) {
+    const schema = {};
+    for (const [name, tool] of Object.entries(tools)) {
+        schema[name] = {
+            description: tool.description,
+            parameters: tool.parameters,
+        };
+    }
+    return schema;
+}
+/**
+ * Filter available CrewTools by persona permissions and sub-agent restrictions.
+ *
+ * Supports tool group expansion: persona specs may use category names
+ * (e.g. "write-code", "git") which are expanded to individual tool names
+ * before matching against the registry.
+ */
+export function filterCrewTools(available, permitted, denied, subAgentTools) {
+    const expandedPermitted = expandToolNames(permitted);
+    const expandedDenied = expandToolNames(denied);
+    const expandedSubAgent = subAgentTools ? expandToolNames(subAgentTools) : undefined;
+    const filtered = {};
+    for (const [name, tool] of Object.entries(available)) {
+        if (expandedDenied.has(name))
+            continue;
+        if (!expandedPermitted.has(name))
+            continue;
+        if (expandedSubAgent && !expandedSubAgent.has(name))
+            continue;
+        filtered[name] = tool;
+    }
+    return filtered;
+}
+export async function executeWithToolDispatch(options) {
+    const { callOptions, tools, context, maxRounds = DEFAULT_MAX_ROUNDS } = options;
+    const schemaTools = toSchemaOnlyToolSet(tools);
+    const messages = [...callOptions.messages];
+    const allExecutions = [];
+    let totalTokensIn = 0;
+    let totalTokensOut = 0;
+    let totalDurationMs = 0;
+    let lastModel = '';
+    for (let round = 0; round < maxRounds; round++) {
+        const result = await callLlm({
+            ...callOptions,
+            messages,
+            tools: schemaTools,
+        });
+        totalTokensIn += result.tokensIn;
+        totalTokensOut += result.tokensOut;
+        totalDurationMs += result.durationMs;
+        lastModel = result.model;
+        if (result.toolCalls.length === 0) {
+            return {
+                text: result.text,
+                toolExecutions: allExecutions,
+                totalTokensIn,
+                totalTokensOut,
+                totalDurationMs,
+                rounds: round + 1,
+                model: lastModel,
+            };
+        }
+        if (result.text) {
+            messages.push({ role: 'assistant', content: result.text });
+        }
+        for (const tc of result.toolCalls) {
+            const execution = await dispatchToolCall(tc, tools, context);
+            allExecutions.push(execution);
+            messages.push({
+                role: 'tool',
+                toolCallId: tc.toolCallId,
+                toolName: tc.toolName,
+                content: execution.success
+                    ? execution.outputSummary
+                    : `Error: ${execution.errorCode ?? 'TOOL_EXECUTION_FAILED'}: ${execution.outputSummary}`,
+            });
+        }
+    }
+    return {
+        text: '',
+        toolExecutions: allExecutions,
+        totalTokensIn,
+        totalTokensOut,
+        totalDurationMs,
+        rounds: maxRounds,
+        model: lastModel,
+    };
+}
+async function dispatchToolCall(tc, tools, context) {
+    const tool = tools[tc.toolName];
+    const startMs = Date.now();
+    if (!tool) {
+        return {
+            toolCallId: tc.toolCallId,
+            toolName: tc.toolName,
+            inputSummary: summarize(tc.input),
+            outputSummary: `Tool not found: ${tc.toolName}`,
+            durationMs: 0,
+            success: false,
+            errorCode: 'TOOL_NOT_FOUND',
+        };
+    }
+    try {
+        const result = await tool.execute(tc.input, context);
+        const durationMs = Date.now() - startMs;
+        return {
+            toolCallId: tc.toolCallId,
+            toolName: tc.toolName,
+            inputSummary: summarize(tc.input),
+            outputSummary: summarize(result),
+            durationMs,
+            success: true,
+        };
+    }
+    catch (err) {
+        const durationMs = Date.now() - startMs;
+        const errorCode = err && typeof err === 'object' && 'code' in err
+            ? String(err.code)
+            : 'TOOL_EXECUTION_FAILED';
+        return {
+            toolCallId: tc.toolCallId,
+            toolName: tc.toolName,
+            inputSummary: summarize(tc.input),
+            outputSummary: err instanceof Error ? err.message : String(err),
+            durationMs,
+            success: false,
+            errorCode,
+        };
+    }
+}
+function summarize(value) {
+    const str = typeof value === 'string' ? value : JSON.stringify(value);
+    return str.length > 500 ? str.slice(0, 497) + '...' : str;
+}

package/dist/engine/tool-dispatch.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-dispatch.test.d.ts.map

package/dist/engine/tool-dispatch.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-dispatch.test.d.ts","sourceRoot":"","sources":["../../src/engine/tool-dispatch.test.ts"],"names":[],"mappings":""}

package/dist/engine/tool-dispatch.test.js

@@ -0,0 +1,348 @@
+import { describe, it, expect, vi } from 'vitest';
+import { toSchemaOnlyToolSet, filterCrewTools, executeWithToolDispatch } from './tool-dispatch.js';
+function makeTool(name) {
+    return {
+        name,
+        description: `Test tool: ${name}`,
+        parameters: { type: 'object', properties: {} },
+        execute: vi.fn().mockResolvedValue({ ok: true }),
+    };
+}
+const mockContext = {
+    workspacePath: '/tmp/ws',
+    targetRepoPath: '/tmp/target',
+    project: {
+        project: { name: 'test', key: 'T' },
+        workspace: { path: '/tmp/ws', work: 'work/{EPIC_ID}', runs: 'runs' },
+        source: { repo: 'github:test/repo', path: '/tmp/target' },
+        llm: { default_model: 'test', providers: {} },
+    },
+    persona: 'engineer',
+    task: 'implement-story',
+    runId: 'run-test-001',
+    protectedPaths: ['product/**', 'AGENTS.md'],
+    logger: () => { },
+};
+describe('tool-dispatch', () => {
+    // T-02-006a: tool-name/runtime alignment
+    describe('toSchemaOnlyToolSet', () => {
+        it('strips execute and preserves schema fields', () => {
+            const tools = {
+                'read-file': makeTool('read-file'),
+                'write-file': makeTool('write-file'),
+            };
+            const schema = toSchemaOnlyToolSet(tools);
+            expect(Object.keys(schema)).toEqual(['read-file', 'write-file']);
+            expect(schema['read-file']).toHaveProperty('description');
+            expect(schema['read-file']).toHaveProperty('parameters');
+            expect(schema['read-file']).not.toHaveProperty('execute');
+        });
+    });
+    // T-02-006b: public export contract -- CrewToolSet filters by permission
+    describe('filterCrewTools', () => {
+        it('filters by permitted and denied sets', () => {
+            const all = {
+                'read-file': makeTool('read-file'),
+                'write-file': makeTool('write-file'),
+                'git-branch': makeTool('git-branch'),
+                'write-strategy-artifacts': makeTool('write-strategy-artifacts'),
+            };
+            const filtered = filterCrewTools(all, new Set(['read-file', 'write-file', 'git-branch', 'write-strategy-artifacts']), new Set(['write-strategy-artifacts']));
+            expect(Object.keys(filtered).sort()).toEqual(['git-branch', 'read-file', 'write-file']);
+        });
+        it('further restricts by sub-agent tools list', () => {
+            const all = {
+                'read-file': makeTool('read-file'),
+                'write-file': makeTool('write-file'),
+                'run-command': makeTool('run-command'),
+            };
+            const filtered = filterCrewTools(all, new Set(['read-file', 'write-file', 'run-command']), new Set(), ['run-command']);
+            expect(Object.keys(filtered)).toEqual(['run-command']);
+        });
+        it('expands tool group names in permitted set', () => {
+            const all = {
+                'read-file': makeTool('read-file'),
+                'write-file': makeTool('write-file'),
+                'list-directory': makeTool('list-directory'),
+                'git-branch': makeTool('git-branch'),
+                'run-command': makeTool('run-command'),
+            };
+            const filtered = filterCrewTools(all, new Set(['code', 'git-operations', 'shell']), new Set());
+            expect(Object.keys(filtered).sort()).toEqual([
+                'git-branch',
+                'list-directory',
+                'read-file',
+                'run-command',
+                'write-file',
+            ]);
+        });
+        it('expands tool group names in sub-agent tools', () => {
+            const all = {
+                'read-file': makeTool('read-file'),
+                'write-file': makeTool('write-file'),
+                'git-branch': makeTool('git-branch'),
+                'git-commit': makeTool('git-commit'),
+                'run-command': makeTool('run-command'),
+            };
+            const filtered = filterCrewTools(all, new Set(['code', 'git-operations', 'shell']), new Set(), ['code', 'git']);
+            expect(Object.keys(filtered).sort()).toEqual([
+                'git-branch',
+                'git-commit',
+                'read-file',
+                'write-file',
+            ]);
+            expect(filtered['run-command']).toBeUndefined();
+        });
+        it('expands tool group names in denied set', () => {
+            const all = {
+                'read-file': makeTool('read-file'),
+                'write-file': makeTool('write-file'),
+                'git-branch': makeTool('git-branch'),
+            };
+            const filtered = filterCrewTools(all, new Set(['code', 'git-operations']), new Set(['git-operations']));
+            expect(Object.keys(filtered).sort()).toEqual(['read-file', 'write-file']);
+        });
+        it('matches Engineer implementer tools correctly', () => {
+            const all = {
+                'read-file': makeTool('read-file'),
+                'write-file': makeTool('write-file'),
+                'list-directory': makeTool('list-directory'),
+                'search-codebase': makeTool('search-codebase'),
+                'git-branch': makeTool('git-branch'),
+                'git-commit': makeTool('git-commit'),
+                'git-push': makeTool('git-push'),
+                'git-diff': makeTool('git-diff'),
+                'git-log': makeTool('git-log'),
+                'create-pr': makeTool('create-pr'),
+                'run-command': makeTool('run-command'),
+            };
+            const filtered = filterCrewTools(all, new Set(['read-artifact', 'write-artifact', 'code', 'git-operations', 'shell']), new Set(['write-strategy-artifacts', 'write-standards']), ['code', 'git', 'shell']);
+            expect(Object.keys(filtered).sort()).toEqual([
+                'create-pr',
+                'git-branch',
+                'git-commit',
+                'git-diff',
+                'git-log',
+                'git-push',
+                'list-directory',
+                'read-file',
+                'run-command',
+                'search-codebase',
+                'write-file',
+            ]);
+        });
+        it('matches Reviewer tools correctly -- read-only, no write-code or git-write', () => {
+            const all = {
+                'read-file': makeTool('read-file'),
+                'write-file': makeTool('write-file'),
+                'list-directory': makeTool('list-directory'),
+                'search-codebase': makeTool('search-codebase'),
+                'git-branch': makeTool('git-branch'),
+                'git-commit': makeTool('git-commit'),
+                'git-push': makeTool('git-push'),
+                'git-diff': makeTool('git-diff'),
+                'git-log': makeTool('git-log'),
+                'create-pr': makeTool('create-pr'),
+                'run-command': makeTool('run-command'),
+                'read-artifact': makeTool('read-artifact'),
+                'write-artifact': makeTool('write-artifact'),
+            };
+            const filtered = filterCrewTools(all, new Set(['read-artifact', 'write-artifact', 'read-code', 'git-read', 'shell']), new Set(['write-code', 'git-write']), ['read-artifact', 'read-code', 'git-read', 'shell']);
+            expect(Object.keys(filtered).sort()).toEqual([
+                'git-diff',
+                'git-log',
+                'list-directory',
+                'read-artifact',
+                'read-file',
+                'run-command',
+                'search-codebase',
+            ]);
+            expect(filtered['write-file']).toBeUndefined();
+            expect(filtered['git-branch']).toBeUndefined();
+            expect(filtered['git-commit']).toBeUndefined();
+            expect(filtered['git-push']).toBeUndefined();
+            expect(filtered['create-pr']).toBeUndefined();
+        });
+    });
+    // T-02-006c: dispatch loop handles tool calls and returns results
+    describe('executeWithToolDispatch', () => {
+        it('returns text directly when no tool calls', async () => {
+            const mockProvider = {
+                generateText: vi.fn().mockResolvedValue({
+                    text: 'Final answer',
+                    toolCalls: [],
+                    tokensIn: 100,
+                    tokensOut: 50,
+                }),
+            };
+            const result = await executeWithToolDispatch({
+                callOptions: {
+                    provider: mockProvider,
+                    model: {
+                        alias: 'test',
+                        provider: 'test',
+                        concreteModel: 'test-model',
+                        apiKeyEnv: 'TEST_KEY',
+                    },
+                    system: 'You are a test.',
+                    messages: [{ role: 'user', content: 'Hello' }],
+                },
+                tools: {},
+                context: mockContext,
+            });
+            expect(result.text).toBe('Final answer');
+            expect(result.toolExecutions).toEqual([]);
+            expect(result.rounds).toBe(1);
+        });
+        it('dispatches tool calls and feeds results back', async () => {
+            const readTool = makeTool('read-file');
+            readTool.execute.mockResolvedValue({ content: 'file content' });
+            const mockProvider = {
+                generateText: vi
+                    .fn()
+                    .mockResolvedValueOnce({
+                    text: '',
+                    toolCalls: [
+                        { toolCallId: 'tc-1', toolName: 'read-file', input: { path: 'src/app.ts' } },
+                    ],
+                    tokensIn: 100,
+                    tokensOut: 50,
+                })
+                    .mockResolvedValueOnce({
+                    text: 'Done reading the file.',
+                    toolCalls: [],
+                    tokensIn: 200,
+                    tokensOut: 100,
+                }),
+            };
+            const result = await executeWithToolDispatch({
+                callOptions: {
+                    provider: mockProvider,
+                    model: {
+                        alias: 'test',
+                        provider: 'test',
+                        concreteModel: 'test-model',
+                        apiKeyEnv: 'TEST_KEY',
+                    },
+                    system: 'You are a test.',
+                    messages: [{ role: 'user', content: 'Read app.ts' }],
+                },
+                tools: { 'read-file': readTool },
+                context: mockContext,
+            });
+            expect(result.text).toBe('Done reading the file.');
+            expect(result.toolExecutions.length).toBe(1);
+            expect(result.toolExecutions[0].toolName).toBe('read-file');
+            expect(result.toolExecutions[0].success).toBe(true);
+            expect(result.rounds).toBe(2);
+            expect(result.totalTokensIn).toBe(300);
+        });
+        it('records failed tool executions without crashing the loop', async () => {
+            const failTool = {
+                name: 'fail-tool',
+                description: 'Always fails',
+                parameters: {},
+                execute: () => Promise.reject(new Error('Boom')),
+            };
+            const mockProvider = {
+                generateText: vi
+                    .fn()
+                    .mockResolvedValueOnce({
+                    text: '',
+                    toolCalls: [{ toolCallId: 'tc-1', toolName: 'fail-tool', input: {} }],
+                    tokensIn: 50,
+                    tokensOut: 20,
+                })
+                    .mockResolvedValueOnce({
+                    text: 'Handled error.',
+                    toolCalls: [],
+                    tokensIn: 80,
+                    tokensOut: 30,
+                }),
+            };
+            const result = await executeWithToolDispatch({
+                callOptions: {
+                    provider: mockProvider,
+                    model: {
+                        alias: 'test',
+                        provider: 'test',
+                        concreteModel: 'test-model',
+                        apiKeyEnv: 'TEST_KEY',
+                    },
+                    system: 'You are a test.',
+                    messages: [{ role: 'user', content: 'Try failing' }],
+                },
+                tools: { 'fail-tool': failTool },
+                context: mockContext,
+            });
+            expect(result.toolExecutions.length).toBe(1);
+            expect(result.toolExecutions[0].success).toBe(false);
+            expect(result.toolExecutions[0].outputSummary).toContain('Boom');
+            expect(result.text).toBe('Handled error.');
+        });
+        it('rejects tool calls for tools not in the filtered set', async () => {
+            const mockProvider = {
+                generateText: vi
+                    .fn()
+                    .mockResolvedValueOnce({
+                    text: '',
+                    toolCalls: [{ toolCallId: 'tc-1', toolName: 'unknown-tool', input: {} }],
+                    tokensIn: 50,
+                    tokensOut: 20,
+                })
+                    .mockResolvedValueOnce({
+                    text: 'OK.',
+                    toolCalls: [],
+                    tokensIn: 50,
+                    tokensOut: 20,
+                }),
+            };
+            const result = await executeWithToolDispatch({
+                callOptions: {
+                    provider: mockProvider,
+                    model: {
+                        alias: 'test',
+                        provider: 'test',
+                        concreteModel: 'test-model',
+                        apiKeyEnv: 'TEST_KEY',
+                    },
+                    system: 'test',
+                    messages: [{ role: 'user', content: 'test' }],
+                },
+                tools: {},
+                context: mockContext,
+            });
+            expect(result.toolExecutions[0].success).toBe(false);
+            expect(result.toolExecutions[0].errorCode).toBe('TOOL_NOT_FOUND');
+        });
+        it('stops after maxRounds', async () => {
+            const tool = makeTool('loop-tool');
+            const mockProvider = {
+                generateText: vi.fn().mockResolvedValue({
+                    text: '',
+                    toolCalls: [{ toolCallId: 'tc-1', toolName: 'loop-tool', input: {} }],
+                    tokensIn: 10,
+                    tokensOut: 5,
+                }),
+            };
+            const result = await executeWithToolDispatch({
+                callOptions: {
+                    provider: mockProvider,
+                    model: {
+                        alias: 'test',
+                        provider: 'test',
+                        concreteModel: 'test-model',
+                        apiKeyEnv: 'TEST_KEY',
+                    },
+                    system: 'test',
+                    messages: [{ role: 'user', content: 'test' }],
+                },
+                tools: { 'loop-tool': tool },
+                context: mockContext,
+                maxRounds: 3,
+            });
+            expect(result.rounds).toBe(3);
+            expect(result.toolExecutions.length).toBe(3);
+        });
+    });
+});

package/dist/engine/tool-filter.d.ts

@@ -0,0 +1,13 @@
+import type { ToolPermissions, ToolSet } from '../types/index.js';
+/**
+ * Filter a set of available tools based on the persona's tool permissions.
+ *
+ * Only tools whose names appear in `permitted` and do NOT appear in `denied`
+ * are returned. The runtime enforces this boundary -- the LLM never sees
+ * tools outside the permitted set.
+ *
+ * If a sub-agent declares a `tools` restriction, apply it as an additional
+ * subset filter on top of the persona-level permissions.
+ */
+export declare function filterTools(available: ToolSet, permissions: ToolPermissions, subAgentTools?: string[]): ToolSet;
+//# sourceMappingURL=tool-filter.d.ts.map

package/dist/engine/tool-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-filter.d.ts","sourceRoot":"","sources":["../../src/engine/tool-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAElE;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,OAAO,EAClB,WAAW,EAAE,eAAe,EAC5B,aAAa,CAAC,EAAE,MAAM,EAAE,GACvB,OAAO,CAcT"}

package/dist/engine/tool-filter.js

@@ -0,0 +1,25 @@
+/**
+ * Filter a set of available tools based on the persona's tool permissions.
+ *
+ * Only tools whose names appear in `permitted` and do NOT appear in `denied`
+ * are returned. The runtime enforces this boundary -- the LLM never sees
+ * tools outside the permitted set.
+ *
+ * If a sub-agent declares a `tools` restriction, apply it as an additional
+ * subset filter on top of the persona-level permissions.
+ */
+export function filterTools(available, permissions, subAgentTools) {
+    const denied = new Set(permissions.denied);
+    const permitted = new Set(permissions.permitted);
+    const filtered = {};
+    for (const [name, definition] of Object.entries(available)) {
+        if (denied.has(name))
+            continue;
+        if (!permitted.has(name))
+            continue;
+        if (subAgentTools && !subAgentTools.includes(name))
+            continue;
+        filtered[name] = definition;
+    }
+    return filtered;
+}

package/dist/evaluation/evaluation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=evaluation.test.d.ts.map

package/dist/evaluation/evaluation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluation.test.d.ts","sourceRoot":"","sources":["../../src/evaluation/evaluation.test.ts"],"names":[],"mappings":""}