@helmiq/crew 0.1.0

package/dist/control/run-state.d.ts

@@ -0,0 +1,16 @@
+import type { RunStatus, RunRecord } from '../types/index.js';
+/**
+ * Validate and apply a state transition on a RunRecord.
+ * Returns a new RunRecord with the updated status (and completed_at if terminal).
+ * Throws InvalidStateTransitionError if the transition is not allowed.
+ */
+export declare function transitionState(record: RunRecord, newStatus: RunStatus): RunRecord;
+/**
+ * Persist the run state to `{runDir}/state.json`.
+ */
+export declare function persistState(runDir: string, record: RunRecord): Promise<void>;
+/**
+ * Load run state from `{runDir}/state.json`.
+ */
+export declare function loadState(runDir: string): Promise<RunRecord | null>;
+//# sourceMappingURL=run-state.d.ts.map

package/dist/control/run-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-state.d.ts","sourceRoot":"","sources":["../../src/control/run-state.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAe9D;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,GAAG,SAAS,CAmBlF;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAGnF;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAOzE"}

package/dist/control/run-state.js

@@ -0,0 +1,55 @@
+import { writeFile, readFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { InvalidStateTransitionError } from '../common/errors.js';
+const VALID_TRANSITIONS = {
+    queued: ['running'],
+    running: ['evaluating', 'failed'],
+    evaluating: ['publishing', 'failed'],
+    publishing: ['published', 'failed', 'awaiting_review'],
+    published: [],
+    failed: [],
+    awaiting_review: ['approved', 'rejected'],
+    approved: [],
+    rejected: [],
+};
+/**
+ * Validate and apply a state transition on a RunRecord.
+ * Returns a new RunRecord with the updated status (and completed_at if terminal).
+ * Throws InvalidStateTransitionError if the transition is not allowed.
+ */
+export function transitionState(record, newStatus) {
+    const allowed = VALID_TRANSITIONS[record.status];
+    if (!allowed || !allowed.includes(newStatus)) {
+        throw new InvalidStateTransitionError(record.status, newStatus, {
+            runId: record.run_id,
+        });
+    }
+    const isTerminal = newStatus === 'published' ||
+        newStatus === 'failed' ||
+        newStatus === 'approved' ||
+        newStatus === 'rejected';
+    return {
+        ...record,
+        status: newStatus,
+        completed_at: isTerminal ? new Date().toISOString() : record.completed_at,
+    };
+}
+/**
+ * Persist the run state to `{runDir}/state.json`.
+ */
+export async function persistState(runDir, record) {
+    await mkdir(runDir, { recursive: true });
+    await writeFile(join(runDir, 'state.json'), JSON.stringify(record, null, 2), 'utf-8');
+}
+/**
+ * Load run state from `{runDir}/state.json`.
+ */
+export async function loadState(runDir) {
+    try {
+        const raw = await readFile(join(runDir, 'state.json'), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/engine/composite.d.ts

@@ -0,0 +1,34 @@
+import type { PersonaSpec, CompositeTask, LlmProvider } from '../types/index.js';
+import type { CrewToolSet, ToolExecutionContext, ToolExecutionRecord } from '../types/tool-runtime.js';
+import type { ResolvedModel } from '../config/model-resolver.js';
+import type { AssembledContext } from '../context/assembler.js';
+import type { ResolvedSkills } from '../config/resolver.js';
+import type { ToolDispatchResult } from './tool-dispatch.js';
+import type { EngineResult } from './simple.js';
+export interface CheckpointRecord {
+    step: number;
+    name: string;
+    path: string;
+}
+export interface SubAgentRecord {
+    name: string;
+    result: ToolDispatchResult;
+    toolExecutions: ToolExecutionRecord[];
+}
+export interface CompositeResult extends EngineResult {
+    checkpoints: CheckpointRecord[];
+    subAgentResults: SubAgentRecord[];
+    toolExecutions: ToolExecutionRecord[];
+}
+/**
+ * Execute a composite (sub-agent pipeline) persona task.
+ *
+ * Per ADR-0014, all sub-agents go through executeWithToolDispatch
+ * for uniform tool execution. Sub-agents with no tools get an empty
+ * CrewToolSet and the dispatch loop exits in one round.
+ *
+ * Per ADR-0016, working state remains Map<string, string>.
+ * ToolDispatchResult.text is stored as the working state value.
+ */
+export declare function executeCompositeTask(persona: PersonaSpec, task: CompositeTask, context: AssembledContext, model: ResolvedModel, provider: LlmProvider, availableTools: CrewToolSet, runDir: string, skills?: ResolvedSkills, toolContext?: ToolExecutionContext): Promise<CompositeResult>;
+//# sourceMappingURL=composite.d.ts.map

package/dist/engine/composite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../src/engine/composite.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EAEb,WAAW,EAEZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,WAAW,EACX,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAI5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,kBAAkB,CAAC;IAC3B,cAAc,EAAE,mBAAmB,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,cAAc,EAAE,mBAAmB,EAAE,CAAC;CACvC;AAwFD;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,WAAW,EACrB,cAAc,EAAE,WAAW,EAC3B,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,cAAmB,EAC3B,WAAW,CAAC,EAAE,oBAAoB,GACjC,OAAO,CAAC,eAAe,CAAC,CA0I1B"}

package/dist/engine/composite.js

@@ -0,0 +1,192 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createNullToolContext } from '../types/tool-runtime.js';
+import { callLlm } from './llm-client.js';
+import { filterCrewTools } from './tool-dispatch.js';
+import { executeWithToolDispatch } from './tool-dispatch.js';
+function buildSubAgentPrompt(agent, workingState, initialContext, skills) {
+    const parts = [];
+    parts.push(`Sub-task: ${agent.produces}`);
+    const skillContent = skills[agent.skill];
+    if (skillContent) {
+        parts.push(`\nInstructions:\n${skillContent}`);
+    }
+    if (initialContext.blocks.length > 0) {
+        parts.push('\n--- Base Context ---');
+        for (const block of initialContext.blocks) {
+            const label = block.source.type + (block.source.path ? ` (${block.source.path})` : '');
+            parts.push(`\n[${label}]\n${block.content}`);
+        }
+        parts.push('--- End Base Context ---');
+    }
+    const relevantReads = agent.reads.filter((r) => workingState.has(r));
+    if (relevantReads.length > 0) {
+        parts.push('\n--- Working State ---');
+        for (const key of relevantReads) {
+            parts.push(`\n[${key}]\n${workingState.get(key)}`);
+        }
+        parts.push('--- End Working State ---');
+    }
+    return parts.join('\n');
+}
+async function checkpoint(runDir, step, name, content) {
+    const workDir = join(runDir, 'work');
+    await mkdir(workDir, { recursive: true });
+    const paddedStep = String(step + 1).padStart(2, '0');
+    const filePath = join(workDir, `${paddedStep}-${name}.md`);
+    await writeFile(filePath, content, 'utf-8');
+    return filePath;
+}
+async function evaluateGate(gateExpression, subAgentOutput, provider, model) {
+    const result = await callLlm({
+        provider,
+        model,
+        system: 'You are a gate evaluator. Assess whether the output meets the gate condition. Respond with exactly one JSON object: { "pass": true/false, "reason": "brief explanation" }. No other text.',
+        messages: [
+            {
+                role: 'user',
+                content: `Gate condition: ${gateExpression}\n\n--- Output to evaluate ---\n${subAgentOutput}\n--- End output ---`,
+            },
+        ],
+        maxRetries: 1,
+    });
+    try {
+        const parsed = JSON.parse(result.text);
+        return {
+            pass: parsed.pass === true,
+            reason: parsed.reason ?? '',
+        };
+    }
+    catch {
+        return { pass: true, reason: 'Gate evaluation produced non-JSON output; defaulting to pass' };
+    }
+}
+/**
+ * Execute a composite (sub-agent pipeline) persona task.
+ *
+ * Per ADR-0014, all sub-agents go through executeWithToolDispatch
+ * for uniform tool execution. Sub-agents with no tools get an empty
+ * CrewToolSet and the dispatch loop exits in one round.
+ *
+ * Per ADR-0016, working state remains Map<string, string>.
+ * ToolDispatchResult.text is stored as the working state value.
+ */
+export async function executeCompositeTask(persona, task, context, model, provider, availableTools, runDir, skills = {}, toolContext) {
+    const workingState = new Map();
+    const checkpoints = [];
+    const subAgentResults = [];
+    const allToolExecutions = [];
+    const loopCounts = new Map();
+    let totalTokensIn = 0;
+    let totalTokensOut = 0;
+    const startMs = Date.now();
+    const systemPrompt = `You are a ${persona.persona.identity.role}.\n\nFollow your prompt instructions precisely. Produce the requested artifact.`;
+    const permittedSet = new Set(persona.persona.tools.permitted);
+    const deniedSet = new Set(persona.persona.tools.denied);
+    let i = 0;
+    while (i < task.sub_agents.length) {
+        const agent = task.sub_agents[i];
+        const filteredTools = filterCrewTools(availableTools, permittedSet, deniedSet, agent.tools);
+        const userPrompt = buildSubAgentPrompt(agent, workingState, context, skills);
+        let dispatchResult = null;
+        let succeeded = false;
+        const maxAttempts = agent.max_iterations ?? 1;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                dispatchResult = await executeWithToolDispatch({
+                    callOptions: {
+                        provider,
+                        model,
+                        system: systemPrompt,
+                        messages: [{ role: 'user', content: userPrompt }],
+                    },
+                    tools: filteredTools,
+                    context: toolContext ?? createNullToolContext(persona.persona.name, task.published_artifact),
+                    maxRounds: 8,
+                });
+                succeeded = true;
+                break;
+            }
+            catch {
+                if (attempt === maxAttempts - 1) {
+                    succeeded = false;
+                }
+            }
+        }
+        if (!succeeded || !dispatchResult) {
+            return {
+                content: '',
+                toolCalls: [],
+                tokensIn: totalTokensIn,
+                tokensOut: totalTokensOut,
+                durationMs: Date.now() - startMs,
+                model: model.concreteModel,
+                checkpoints,
+                subAgentResults,
+                toolExecutions: allToolExecutions,
+            };
+        }
+        totalTokensIn += dispatchResult.totalTokensIn;
+        totalTokensOut += dispatchResult.totalTokensOut;
+        allToolExecutions.push(...dispatchResult.toolExecutions);
+        subAgentResults.push({
+            name: agent.name,
+            result: dispatchResult,
+            toolExecutions: dispatchResult.toolExecutions,
+        });
+        const checkpointPath = await checkpoint(runDir, i, agent.name, dispatchResult.text);
+        checkpoints.push({ step: i, name: agent.name, path: checkpointPath });
+        workingState.set(agent.produces, dispatchResult.text);
+        if (agent.gate && agent.on_fail) {
+            const gateResult = await evaluateGate(agent.gate, dispatchResult.text, provider, model);
+            if (!gateResult.pass) {
+                const loopKey = agent.name;
+                const currentCount = (loopCounts.get(loopKey) ?? 0) + 1;
+                loopCounts.set(loopKey, currentCount);
+                if (currentCount >= (agent.max_loops ?? 1)) {
+                    return {
+                        content: '',
+                        toolCalls: [],
+                        tokensIn: totalTokensIn,
+                        tokensOut: totalTokensOut,
+                        durationMs: Date.now() - startMs,
+                        model: model.concreteModel,
+                        checkpoints,
+                        subAgentResults,
+                        toolExecutions: allToolExecutions,
+                    };
+                }
+                const targetIndex = task.sub_agents.findIndex((a) => a.name === agent.on_fail);
+                if (targetIndex === -1) {
+                    return {
+                        content: '',
+                        toolCalls: [],
+                        tokensIn: totalTokensIn,
+                        tokensOut: totalTokensOut,
+                        durationMs: Date.now() - startMs,
+                        model: model.concreteModel,
+                        checkpoints,
+                        subAgentResults,
+                        toolExecutions: allToolExecutions,
+                    };
+                }
+                i = targetIndex;
+                continue;
+            }
+        }
+        i++;
+    }
+    const finalResult = subAgentResults[subAgentResults.length - 1];
+    const finalToolCalls = [];
+    return {
+        content: finalResult?.result.text ?? '',
+        toolCalls: finalToolCalls,
+        tokensIn: totalTokensIn,
+        tokensOut: totalTokensOut,
+        durationMs: Date.now() - startMs,
+        model: model.concreteModel,
+        checkpoints,
+        subAgentResults,
+        toolExecutions: allToolExecutions,
+    };
+}

package/dist/engine/composite.test.d.ts

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

package/dist/engine/composite.test.d.ts.map

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