From 1f359c976b107d37a951c55b8cdfc0de49f0a7df Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Thu, 18 Dec 2025 15:18:46 +0100 Subject: [PATCH 01/16] compiler approach phase 1 --- .../agent/plans/compiler-phase-1-done.md | 39 + .../src/mastra/tools/mock-agent.ts | 423 ++++++++++ .../src/mastra/tools/plan-compiler.test.ts | 739 +++++++++++++++++ .../src/mastra/tools/plan-compiler.ts | 771 ++++++++++++++++++ 4 files changed, 1972 insertions(+) create mode 100644 apps/hash-ai-agent/agent/plans/compiler-phase-1-done.md create mode 100644 apps/hash-ai-agent/src/mastra/tools/mock-agent.ts create mode 100644 apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts create mode 100644 apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts diff --git a/apps/hash-ai-agent/agent/plans/compiler-phase-1-done.md b/apps/hash-ai-agent/agent/plans/compiler-phase-1-done.md new file mode 100644 index 00000000000..4761110029d --- /dev/null +++ b/apps/hash-ai-agent/agent/plans/compiler-phase-1-done.md @@ -0,0 +1,39 @@ +Phase 1 Complete! +I've successfully implemented the plan compiler infrastructure. Here's a summary: +Files Created +| File | Purpose | Lines | +| -------------------------------------- | ------------------------------------ | ----- | +| src/mastra/tools/mock-agent.ts | Deterministic mock agent for testing | ~350 | +| src/mastra/tools/plan-compiler.ts | Compiles PlanSpec → Mastra Workflow | ~540 | +| src/mastra/tools/plan-compiler.test.ts | Integration tests | ~730 | +Test Results +All 20 tests pass: +Compilation Tests (5): +- ✓ Compiles minimal valid plan +- ✓ Compiles linear plan with sequential dependencies +- ✓ Compiles plan with parallel steps +- ✓ Compiles diamond-shaped plan +- ✓ Compiles plan with mixed parallelism +Topology Analysis Tests (7): +- ✓ Correctly identifies entry points +- ✓ Correctly identifies exit points +- ✓ Correctly computes parallel groups for parallel plan +- ✓ Correctly computes parallel groups for diamond plan +- ✓ Correctly computes topological order for linear plan +- ✓ Correctly identifies critical path +- ✓ Correctly identifies parallelizable steps within groups +Execution Tests (4): +- ✓ Executes minimal plan and returns result +- ✓ Executes linear plan in correct order +- ✓ Executes parallel plan respecting dependencies +- ✓ Executes diamond plan respecting dependencies +Streaming Events Tests (4): +- ✓ Emits plan-start event +- ✓ Emits step-start and step-complete events +- ✓ Emits progress events +- ✓ Emits plan-complete event +Key Implementation Details +1. MockAgent - Returns deterministic responses based on step type, includes traceable __mock metadata +2. TopologyAnalyzer integration - Uses your existing analyzer for parallel groups and execution order +3. Streaming events - Six data-plan-* event types flow through writer.custom() +4. Fail-fast error handling - Steps throw on error, workflow stops diff --git a/apps/hash-ai-agent/src/mastra/tools/mock-agent.ts b/apps/hash-ai-agent/src/mastra/tools/mock-agent.ts new file mode 100644 index 00000000000..9e8433a2359 --- /dev/null +++ b/apps/hash-ai-agent/src/mastra/tools/mock-agent.ts @@ -0,0 +1,423 @@ +/** + * Mock Agent — Deterministic Agent for Testing Plan Compilation + * + * Provides a mock implementation of the Mastra Agent interface that returns + * deterministic responses based on step type and prompt patterns. This enables + * testing the plan compiler without incurring LLM API costs. + * + * The mock agent: + * - Returns traceable metadata about what it "executed" + * - Simulates realistic response structures for each step type + * - Can be configured with custom response handlers + * + * @see docs/PLAN-task-decomposition.md for design documentation + */ + +import type { StepType } from "../schemas/plan-spec"; + +// ============================================================================= +// TYPES +// ============================================================================= + +/** + * Metadata included in mock responses for traceability. + */ +export interface MockExecutionMetadata { + __mock: true; + stepId: string; + stepType: StepType; + executorRef: string; + promptReceived: string; + simulatedDurationMs: number; + timestamp: string; +} + +/** + * Mock response structure for research steps. + */ +export interface MockResearchResponse extends MockExecutionMetadata { + stepType: "research"; + papers: string[]; + summaries: string[]; + sourcesSearched: number; +} + +/** + * Mock response structure for synthesize steps. + */ +export interface MockSynthesizeResponse extends MockExecutionMetadata { + stepType: "synthesize"; + synthesis: string; + inputsProcessed: number; + mode: "integrative" | "evaluative"; +} + +/** + * Mock response structure for experiment steps. + */ +export interface MockExperimentResponse extends MockExecutionMetadata { + stepType: "experiment"; + results: Record; + observations: string[]; + hypothesesTested: string[]; + mode: "exploratory" | "confirmatory"; +} + +/** + * Mock response structure for develop steps. + */ +export interface MockDevelopResponse extends MockExecutionMetadata { + stepType: "develop"; + deliverables: string[]; + artifactsProduced: number; +} + +/** + * Union of all mock response types. + */ +export type MockResponse = + | MockResearchResponse + | MockSynthesizeResponse + | MockExperimentResponse + | MockDevelopResponse; + +/** + * Configuration for a mock agent instance. + */ +export interface MockAgentConfig { + /** Agent identifier (matches executor.ref in PlanSpec) */ + id: string; + /** Human-readable name */ + name: string; + /** Simulated response delay in milliseconds (default: 100) */ + simulatedDelayMs?: number; + /** Custom response handler for specific prompts */ + customHandler?: (prompt: string, stepInfo: StepInfo) => MockResponse | null; +} + +/** + * Information about the step being executed, extracted from prompt. + */ +export interface StepInfo { + stepId: string; + stepType: StepType; + description: string; + executorRef: string; +} + +// ============================================================================= +// MOCK AGENT CLASS +// ============================================================================= + +/** + * A deterministic mock agent for testing plan compilation and execution. + * + * This class mimics the Mastra Agent interface but returns predictable + * responses based on step type, enabling testing without LLM calls. + * + * @example + * ```typescript + * const mockAgent = new MockAgent({ + * id: "literature-searcher", + * name: "Mock Literature Searcher", + * }); + * + * const response = await mockAgent.generate("Research: Find papers on RAG"); + * // Returns deterministic MockResearchResponse + * ``` + */ +export class MockAgent { + readonly id: string; + readonly name: string; + private simulatedDelayMs: number; + private customHandler?: ( + prompt: string, + stepInfo: StepInfo, + ) => MockResponse | null; + + constructor(config: MockAgentConfig) { + this.id = config.id; + this.name = config.name; + this.simulatedDelayMs = config.simulatedDelayMs ?? 100; + this.customHandler = config.customHandler; + } + + /** + * Generate a mock response for the given prompt. + * + * Parses the prompt to extract step information and returns a + * deterministic response based on the step type. + */ + async generate( + prompt: string, + _options?: unknown, + ): Promise<{ text: string; object: MockResponse }> { + // Simulate processing delay + if (this.simulatedDelayMs > 0) { + await this.delay(this.simulatedDelayMs); + } + + // Extract step info from prompt + const stepInfo = this.extractStepInfo(prompt); + + // Try custom handler first + if (this.customHandler) { + const customResponse = this.customHandler(prompt, stepInfo); + if (customResponse) { + return { + text: JSON.stringify(customResponse, null, 2), + object: customResponse, + }; + } + } + + // Generate default response based on step type + const response = this.generateDefaultResponse(prompt, stepInfo); + + return { + text: JSON.stringify(response, null, 2), + object: response, + }; + } + + /** + * Stream a mock response (returns same as generate, wrapped in async iterator). + * + * For mock purposes, this immediately yields the full response. + * The returned object has a similar shape to Mastra's stream response. + */ + async stream( + prompt: string, + _options?: unknown, + ): Promise<{ + fullStream: ReadableStream<{ type: string; text?: string }>; + text: Promise; + object: Promise; + }> { + const { text, object } = await this.generate(prompt, _options); + + // Create a simple readable stream that emits the text + const chunks = this.chunkText(text, 50); // 50 char chunks + let chunkIndex = 0; + + const fullStream = new ReadableStream<{ type: string; text?: string }>({ + pull(controller) { + if (chunkIndex < chunks.length) { + controller.enqueue({ type: "text-delta", text: chunks[chunkIndex] }); + chunkIndex++; + } else { + controller.enqueue({ type: "finish" }); + controller.close(); + } + }, + }); + + return { + fullStream, + text: Promise.resolve(text), + object: Promise.resolve(object), + }; + } + + /** + * Extract step information from the prompt. + * + * Looks for patterns like: + * - "## Task: " + * - "Step ID: " + * - Step type indicators in the content + */ + private extractStepInfo(prompt: string): StepInfo { + // Default values + let stepId = "unknown"; + let stepType: StepType = "research"; + let description = "Unknown step"; + + // Extract step ID from prompt patterns + const stepIdMatch = prompt.match(/step[_\s]?id[:\s]+["']?(\w+)["']?/i); + if (stepIdMatch) { + stepId = stepIdMatch[1]!; + } + + // Extract description from "## Task:" section + const taskMatch = prompt.match(/##\s*Task:\s*(.+?)(?:\n|$)/i); + if (taskMatch) { + description = taskMatch[1]!.trim(); + } + + // Infer step type from prompt content + if ( + prompt.toLowerCase().includes("research") || + prompt.toLowerCase().includes("query:") + ) { + stepType = "research"; + } else if ( + prompt.toLowerCase().includes("synthesize") || + prompt.toLowerCase().includes("mode: integrative") || + prompt.toLowerCase().includes("mode: evaluative") + ) { + stepType = "synthesize"; + } else if ( + prompt.toLowerCase().includes("experiment") || + prompt.toLowerCase().includes("procedure:") + ) { + stepType = "experiment"; + } else if ( + prompt.toLowerCase().includes("develop") || + prompt.toLowerCase().includes("specification:") + ) { + stepType = "develop"; + } + + return { + stepId, + stepType, + description, + executorRef: this.id, + }; + } + + /** + * Generate a default mock response based on step type. + */ + private generateDefaultResponse( + prompt: string, + stepInfo: StepInfo, + ): MockResponse { + const baseMetadata: MockExecutionMetadata = { + __mock: true, + stepId: stepInfo.stepId, + stepType: stepInfo.stepType, + executorRef: stepInfo.executorRef, + promptReceived: prompt.slice(0, 200) + (prompt.length > 200 ? "..." : ""), + simulatedDurationMs: this.simulatedDelayMs, + timestamp: new Date().toISOString(), + }; + + switch (stepInfo.stepType) { + case "research": + return { + ...baseMetadata, + stepType: "research", + papers: [ + `mock-paper-1-for-${stepInfo.stepId}`, + `mock-paper-2-for-${stepInfo.stepId}`, + ], + summaries: [ + `Summary of findings for ${stepInfo.description}`, + `Additional insights from research`, + ], + sourcesSearched: 5, + }; + + case "synthesize": { + const isEvaluative = prompt.toLowerCase().includes("evaluative"); + return { + ...baseMetadata, + stepType: "synthesize", + synthesis: `Synthesized understanding of ${stepInfo.description}. Key themes identified and integrated.`, + inputsProcessed: 3, + mode: isEvaluative ? "evaluative" : "integrative", + }; + } + + case "experiment": { + const isConfirmatory = prompt.toLowerCase().includes("confirmatory"); + return { + ...baseMetadata, + stepType: "experiment", + results: { + metric: 0.85, + passed: true, + sampleSize: 100, + }, + observations: [ + `Observation 1 for ${stepInfo.stepId}`, + `Observation 2 for ${stepInfo.stepId}`, + ], + hypothesesTested: [`H1`], + mode: isConfirmatory ? "confirmatory" : "exploratory", + }; + } + + case "develop": + return { + ...baseMetadata, + stepType: "develop", + deliverables: [ + `deliverable-1-${stepInfo.stepId}`, + `deliverable-2-${stepInfo.stepId}`, + ], + artifactsProduced: 2, + }; + } + } + + /** + * Split text into chunks for simulated streaming. + */ + private chunkText(text: string, chunkSize: number): string[] { + const chunks: string[] = []; + for (let i = 0; i < text.length; i += chunkSize) { + chunks.push(text.slice(i, i + chunkSize)); + } + return chunks; + } + + /** + * Delay helper for simulating processing time. + */ + private delay(ms: number): Promise { + return new Promise((resolve) => setTimeout(resolve, ms)); + } +} + +// ============================================================================= +// MOCK AGENT REGISTRY +// ============================================================================= + +/** + * Creates a registry of mock agents matching the AVAILABLE_AGENTS in constants.ts. + * + * This allows the compiler to resolve executor refs to mock agents for testing. + * + * @example + * ```typescript + * const registry = createMockAgentRegistry(); + * const agent = registry.get("literature-searcher"); + * ``` + */ +export function createMockAgentRegistry( + config: { simulatedDelayMs?: number } = {}, +): Map { + const registry = new Map(); + + // Create mock agents for all available agent refs + const agentRefs = [ + "literature-searcher", + "paper-summarizer", + "concept-explainer", + "result-synthesizer", + "hypothesis-generator", + "progress-evaluator", + "experiment-designer", + "experiment-runner", + "code-explorer", + "code-writer", + "code-reviewer", + "documentation-writer", + ]; + + for (const ref of agentRefs) { + registry.set( + ref, + new MockAgent({ + id: ref, + name: `Mock ${ref}`, + simulatedDelayMs: config.simulatedDelayMs ?? 100, + }), + ); + } + + return registry; +} diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts new file mode 100644 index 00000000000..6486c4974a1 --- /dev/null +++ b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts @@ -0,0 +1,739 @@ +/** + * Plan Compiler Integration Tests + * + * Tests that the plan compiler correctly transforms PlanSpec instances + * into executable Mastra workflows with proper: + * - Execution order (respecting dependencies) + * - Parallel group handling + * - Streaming event emission + * - Mock agent execution + * + * Uses mock agents throughout - no LLM calls. + */ + +import { describe, expect, test } from "vitest"; + +import type { PlanSpec } from "../schemas/plan-spec"; +import { validatePlan } from "./plan-validator"; +import { + compilePlanToWorkflow, + type PlanExecutionEvent, +} from "./plan-compiler"; +import { analyzePlanTopology } from "./topology-analyzer"; + +// ============================================================================= +// TEST HELPERS +// ============================================================================= + +/** + * Creates a minimal valid plan for testing. + * Single research step - the simplest possible plan. + */ +function createMinimalPlan(): PlanSpec { + return { + id: "minimal-plan", + goalSummary: "Minimal test plan", + requirements: [ + { id: "R1", description: "Test requirement", priority: "must" }, + ], + hypotheses: [], + steps: [ + { + type: "research", + id: "S1", + description: "Single research step", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [{ name: "findings", description: "Research findings" }], + query: "Test query", + stoppingRule: "Find 3 sources", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + ], + unknownsMap: { + knownKnowns: ["Test framework works"], + knownUnknowns: ["All edge cases"], + unknownUnknowns: [ + { + potentialSurprise: "Unexpected behavior", + detectionSignal: "Tests fail", + }, + ], + communityCheck: "Code review", + }, + }; +} + +/** + * Creates a linear plan with 3 sequential steps. + * S1 → S2 → S3 + */ +function createLinearPlan(): PlanSpec { + return { + id: "linear-plan", + goalSummary: "Linear sequential plan", + requirements: [ + { id: "R1", description: "Complete all steps", priority: "must" }, + ], + hypotheses: [], + steps: [ + { + type: "research", + id: "S1", + description: "Initial research", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [{ name: "findings", description: "Initial findings" }], + query: "Initial query", + stoppingRule: "Find sources", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "synthesize", + id: "S2", + description: "Synthesize findings", + dependsOn: ["S1"], + requirementIds: ["R1"], + inputs: [ + { name: "findings", description: "From S1", fromStepId: "S1" }, + ], + outputs: [{ name: "synthesis", description: "Synthesized results" }], + mode: "integrative", + inputStepIds: ["S1"], + parallelizable: false, + executor: { kind: "agent", ref: "result-synthesizer" }, + }, + { + type: "develop", + id: "S3", + description: "Produce deliverable", + dependsOn: ["S2"], + requirementIds: ["R1"], + inputs: [ + { name: "synthesis", description: "From S2", fromStepId: "S2" }, + ], + outputs: [{ name: "deliverable", description: "Final output" }], + specification: "Build based on synthesis", + deliverables: ["Documentation"], + parallelizable: false, + executor: { kind: "agent", ref: "documentation-writer" }, + }, + ], + unknownsMap: { + knownKnowns: ["Sequential flow works"], + knownUnknowns: ["Performance characteristics"], + unknownUnknowns: [ + { + potentialSurprise: "Ordering issues", + detectionSignal: "Wrong order", + }, + ], + communityCheck: "Review execution logs", + }, + }; +} + +/** + * Creates a plan with parallel research steps. + * S1, S2, S3 (parallel) → S4 (synthesis) + */ +function createParallelPlan(): PlanSpec { + return { + id: "parallel-plan", + goalSummary: "Parallel research then synthesis", + requirements: [ + { id: "R1", description: "Research multiple topics", priority: "must" }, + ], + hypotheses: [], + steps: [ + { + type: "research", + id: "S1", + description: "Research topic A", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [{ name: "findings_a", description: "Topic A findings" }], + query: "Topic A query", + stoppingRule: "Find 3 sources", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "research", + id: "S2", + description: "Research topic B", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [{ name: "findings_b", description: "Topic B findings" }], + query: "Topic B query", + stoppingRule: "Find 3 sources", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "research", + id: "S3", + description: "Research topic C", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [{ name: "findings_c", description: "Topic C findings" }], + query: "Topic C query", + stoppingRule: "Find 3 sources", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "synthesize", + id: "S4", + description: "Combine all findings", + dependsOn: ["S1", "S2", "S3"], + requirementIds: ["R1"], + inputs: [ + { name: "findings_a", description: "From S1", fromStepId: "S1" }, + { name: "findings_b", description: "From S2", fromStepId: "S2" }, + { name: "findings_c", description: "From S3", fromStepId: "S3" }, + ], + outputs: [{ name: "synthesis", description: "Combined synthesis" }], + mode: "integrative", + inputStepIds: ["S1", "S2", "S3"], + parallelizable: false, + executor: { kind: "agent", ref: "result-synthesizer" }, + }, + ], + unknownsMap: { + knownKnowns: ["Parallel execution supported"], + knownUnknowns: ["Exact parallelism level"], + unknownUnknowns: [ + { + potentialSurprise: "Race conditions", + detectionSignal: "Inconsistent results", + }, + ], + communityCheck: "Verify parallel execution", + }, + }; +} + +/** + * Creates a diamond-shaped plan. + * S1 + * / \ + * S2 S3 + * \ / + * S4 + */ +function createDiamondPlan(): PlanSpec { + return { + id: "diamond-plan", + goalSummary: "Diamond dependency pattern", + requirements: [ + { id: "R1", description: "Handle diamond pattern", priority: "must" }, + ], + hypotheses: [], + steps: [ + { + type: "research", + id: "S1", + description: "Initial research", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [{ name: "initial", description: "Initial data" }], + query: "Initial query", + stoppingRule: "Find sources", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "research", + id: "S2", + description: "Branch A analysis", + dependsOn: ["S1"], + requirementIds: ["R1"], + inputs: [{ name: "initial", description: "From S1", fromStepId: "S1" }], + outputs: [{ name: "branch_a", description: "Branch A results" }], + query: "Branch A query", + stoppingRule: "Analyze branch A", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "research", + id: "S3", + description: "Branch B analysis", + dependsOn: ["S1"], + requirementIds: ["R1"], + inputs: [{ name: "initial", description: "From S1", fromStepId: "S1" }], + outputs: [{ name: "branch_b", description: "Branch B results" }], + query: "Branch B query", + stoppingRule: "Analyze branch B", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "synthesize", + id: "S4", + description: "Merge branches", + dependsOn: ["S2", "S3"], + requirementIds: ["R1"], + inputs: [ + { name: "branch_a", description: "From S2", fromStepId: "S2" }, + { name: "branch_b", description: "From S3", fromStepId: "S3" }, + ], + outputs: [{ name: "merged", description: "Merged results" }], + mode: "integrative", + inputStepIds: ["S2", "S3"], + parallelizable: false, + executor: { kind: "agent", ref: "result-synthesizer" }, + }, + ], + unknownsMap: { + knownKnowns: ["Diamond patterns are valid DAGs"], + knownUnknowns: ["Optimal parallel execution"], + unknownUnknowns: [ + { + potentialSurprise: "Merge conflicts", + detectionSignal: "Data inconsistency", + }, + ], + communityCheck: "Verify fan-in handling", + }, + }; +} + +/** + * Creates a plan with mixed parallelism at the same depth. + * S1 (parallel) and S2 (not parallel) at depth 0. + */ +function createMixedParallelismPlan(): PlanSpec { + return { + id: "mixed-parallelism-plan", + goalSummary: "Mixed parallel and sequential at same depth", + requirements: [ + { id: "R1", description: "Handle mixed parallelism", priority: "must" }, + ], + hypotheses: [], + steps: [ + { + type: "research", + id: "S1", + description: "Parallelizable research", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [{ name: "findings", description: "Findings" }], + query: "Query", + stoppingRule: "Find sources", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "synthesize", + id: "S2", + description: "Non-parallelizable synthesis (no deps)", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [{ name: "synthesis", description: "Synthesis" }], + mode: "integrative", + inputStepIds: [], + parallelizable: false, // Explicitly not parallelizable + executor: { kind: "agent", ref: "result-synthesizer" }, + }, + { + type: "develop", + id: "S3", + description: "Final development", + dependsOn: ["S1", "S2"], + requirementIds: ["R1"], + inputs: [], + outputs: [{ name: "output", description: "Output" }], + specification: "Combine results", + deliverables: ["Final artifact"], + parallelizable: false, + executor: { kind: "agent", ref: "documentation-writer" }, + }, + ], + unknownsMap: { + knownKnowns: ["Mixed parallelism patterns exist"], + knownUnknowns: ["Optimal handling strategy"], + unknownUnknowns: [ + { + potentialSurprise: "Scheduling issues", + detectionSignal: "Unexpected order", + }, + ], + communityCheck: "Review scheduling logic", + }, + }; +} + +// ============================================================================= +// COMPILATION TESTS +// ============================================================================= + +describe("Plan Compiler — Compilation", () => { + describe("Basic compilation", () => { + test("compiles a minimal valid plan", () => { + const plan = createMinimalPlan(); + + // Verify plan is valid first + const validation = validatePlan(plan); + expect(validation.valid).toBe(true); + + // Compile should not throw + const workflow = compilePlanToWorkflow(plan, { useMockAgents: true }); + + expect(workflow).toBeDefined(); + }); + + test("compiles a linear plan with sequential dependencies", () => { + const plan = createLinearPlan(); + + const validation = validatePlan(plan); + expect(validation.valid).toBe(true); + + const workflow = compilePlanToWorkflow(plan, { useMockAgents: true }); + expect(workflow).toBeDefined(); + }); + + test("compiles a plan with parallel steps", () => { + const plan = createParallelPlan(); + + const validation = validatePlan(plan); + expect(validation.valid).toBe(true); + + const workflow = compilePlanToWorkflow(plan, { useMockAgents: true }); + expect(workflow).toBeDefined(); + }); + + test("compiles a diamond-shaped plan", () => { + const plan = createDiamondPlan(); + + const validation = validatePlan(plan); + expect(validation.valid).toBe(true); + + const workflow = compilePlanToWorkflow(plan, { useMockAgents: true }); + expect(workflow).toBeDefined(); + }); + + test("compiles a plan with mixed parallelism", () => { + const plan = createMixedParallelismPlan(); + + const validation = validatePlan(plan); + expect(validation.valid).toBe(true); + + const workflow = compilePlanToWorkflow(plan, { useMockAgents: true }); + expect(workflow).toBeDefined(); + }); + }); +}); + +// ============================================================================= +// TOPOLOGY ANALYSIS TESTS +// ============================================================================= + +describe("Plan Compiler — Topology Analysis", () => { + test("correctly identifies entry points", () => { + const plan = createParallelPlan(); + const topology = analyzePlanTopology(plan); + + // S1, S2, S3 should all be entry points (no dependencies) + expect(topology.entryPoints).toContain("S1"); + expect(topology.entryPoints).toContain("S2"); + expect(topology.entryPoints).toContain("S3"); + expect(topology.entryPoints).not.toContain("S4"); + }); + + test("correctly identifies exit points", () => { + const plan = createParallelPlan(); + const topology = analyzePlanTopology(plan); + + // S4 should be the only exit point (nothing depends on it) + expect(topology.exitPoints).toEqual(["S4"]); + }); + + test("correctly computes parallel groups for parallel plan", () => { + const plan = createParallelPlan(); + const topology = analyzePlanTopology(plan); + + // Should have 2 parallel groups: + // Depth 0: S1, S2, S3 + // Depth 1: S4 + expect(topology.parallelGroups.length).toBe(2); + + const depth0 = topology.parallelGroups.find((g) => g.depth === 0); + const depth1 = topology.parallelGroups.find((g) => g.depth === 1); + + expect(depth0?.stepIds).toHaveLength(3); + expect(depth0?.stepIds).toContain("S1"); + expect(depth0?.stepIds).toContain("S2"); + expect(depth0?.stepIds).toContain("S3"); + + expect(depth1?.stepIds).toHaveLength(1); + expect(depth1?.stepIds).toContain("S4"); + }); + + test("correctly computes parallel groups for diamond plan", () => { + const plan = createDiamondPlan(); + const topology = analyzePlanTopology(plan); + + // Should have 3 parallel groups: + // Depth 0: S1 + // Depth 1: S2, S3 + // Depth 2: S4 + expect(topology.parallelGroups.length).toBe(3); + + const depth0 = topology.parallelGroups.find((g) => g.depth === 0); + const depth1 = topology.parallelGroups.find((g) => g.depth === 1); + const depth2 = topology.parallelGroups.find((g) => g.depth === 2); + + expect(depth0?.stepIds).toEqual(["S1"]); + expect(depth1?.stepIds).toHaveLength(2); + expect(depth1?.stepIds).toContain("S2"); + expect(depth1?.stepIds).toContain("S3"); + expect(depth2?.stepIds).toEqual(["S4"]); + }); + + test("correctly computes topological order for linear plan", () => { + const plan = createLinearPlan(); + const topology = analyzePlanTopology(plan); + + // Topological order should be S1, S2, S3 + expect(topology.topologicalOrder).toEqual(["S1", "S2", "S3"]); + }); + + test("correctly identifies critical path", () => { + const plan = createDiamondPlan(); + const topology = analyzePlanTopology(plan); + + // Critical path should be length 3 (S1 → S2/S3 → S4) + expect(topology.criticalPath.length).toBe(3); + expect(topology.criticalPath.stepIds[0]).toBe("S1"); + expect(topology.criticalPath.stepIds[2]).toBe("S4"); + }); + + test("correctly identifies parallelizable steps within groups", () => { + const plan = createMixedParallelismPlan(); + const topology = analyzePlanTopology(plan); + + const depth0 = topology.parallelGroups.find((g) => g.depth === 0); + + // S1 is parallelizable, S2 is not + expect(depth0?.parallelizableStepIds).toContain("S1"); + expect(depth0?.parallelizableStepIds).not.toContain("S2"); + }); +}); + +// ============================================================================= +// EXECUTION TESTS (with mocks) +// ============================================================================= + +describe("Plan Compiler — Execution", () => { + test("executes minimal plan and returns result", async () => { + const plan = createMinimalPlan(); + const workflow = compilePlanToWorkflow(plan, { + useMockAgents: true, + mockDelayMs: 10, // Fast for testing + }); + + const run = await workflow.createRun(); + const result = await run.start({ inputData: { context: {} } }); + + expect(result.status).toBe("success"); + if (result.status === "success") { + expect(result.result.planId).toBe("minimal-plan"); + expect(result.result.success).toBe(true); + expect(result.result.executionOrder).toEqual(["S1"]); + } + }, 10000); + + test("executes linear plan in correct order", async () => { + const plan = createLinearPlan(); + const workflow = compilePlanToWorkflow(plan, { + useMockAgents: true, + mockDelayMs: 10, + }); + + const run = await workflow.createRun(); + const result = await run.start({ inputData: { context: {} } }); + + expect(result.status).toBe("success"); + if (result.status === "success") { + expect(result.result.success).toBe(true); + expect(result.result.executionOrder).toEqual(["S1", "S2", "S3"]); + } + }, 10000); + + test("executes parallel plan respecting dependencies", async () => { + const plan = createParallelPlan(); + const workflow = compilePlanToWorkflow(plan, { + useMockAgents: true, + mockDelayMs: 10, + }); + + const run = await workflow.createRun(); + const result = await run.start({ inputData: { context: {} } }); + + expect(result.status).toBe("success"); + if (result.status === "success") { + expect(result.result.success).toBe(true); + // S4 should be last (depends on S1, S2, S3) + const order = result.result.executionOrder as string[]; + expect(order[order.length - 1]).toBe("S4"); + } + }, 10000); + + test("executes diamond plan respecting dependencies", async () => { + const plan = createDiamondPlan(); + const workflow = compilePlanToWorkflow(plan, { + useMockAgents: true, + mockDelayMs: 10, + }); + + const run = await workflow.createRun(); + const result = await run.start({ inputData: { context: {} } }); + + expect(result.status).toBe("success"); + if (result.status === "success") { + expect(result.result.success).toBe(true); + const order = result.result.executionOrder as string[]; + + // S1 should be first + expect(order[0]).toBe("S1"); + // S4 should be last + expect(order[order.length - 1]).toBe("S4"); + // S2 and S3 should be between S1 and S4 + const s2Index = order.indexOf("S2"); + const s3Index = order.indexOf("S3"); + expect(s2Index).toBeGreaterThan(0); + expect(s3Index).toBeGreaterThan(0); + expect(s2Index).toBeLessThan(order.length - 1); + expect(s3Index).toBeLessThan(order.length - 1); + } + }, 10000); +}); + +// ============================================================================= +// STREAMING EVENTS TESTS +// ============================================================================= + +describe("Plan Compiler — Streaming Events", () => { + test("emits plan-start event", async () => { + const plan = createMinimalPlan(); + const workflow = compilePlanToWorkflow(plan, { + useMockAgents: true, + mockDelayMs: 10, + }); + + const events: PlanExecutionEvent[] = []; + const run = await workflow.createRun(); + + // Use stream to capture events + const stream = await run.stream({ inputData: { context: {} } }); + + for await (const chunk of stream.fullStream) { + if (chunk.type.startsWith("data-plan-")) { + events.push(chunk as unknown as PlanExecutionEvent); + } + } + + const startEvent = events.find((e) => e.type === "data-plan-start"); + expect(startEvent).toBeDefined(); + expect(startEvent?.data.planId).toBe("minimal-plan"); + expect(startEvent?.data.totalSteps).toBe(1); + }, 10000); + + test("emits step-start and step-complete events", async () => { + const plan = createMinimalPlan(); + const workflow = compilePlanToWorkflow(plan, { + useMockAgents: true, + mockDelayMs: 10, + }); + + const events: PlanExecutionEvent[] = []; + const run = await workflow.createRun(); + const stream = await run.stream({ inputData: { context: {} } }); + + for await (const chunk of stream.fullStream) { + if (chunk.type.startsWith("data-plan-")) { + events.push(chunk as unknown as PlanExecutionEvent); + } + } + + const stepStartEvents = events.filter( + (e) => e.type === "data-plan-step-start", + ); + const stepCompleteEvents = events.filter( + (e) => e.type === "data-plan-step-complete", + ); + + expect(stepStartEvents).toHaveLength(1); + expect(stepCompleteEvents).toHaveLength(1); + + expect(stepStartEvents[0]?.data.stepId).toBe("S1"); + expect(stepCompleteEvents[0]?.data.stepId).toBe("S1"); + }, 10000); + + test("emits progress events", async () => { + const plan = createLinearPlan(); + const workflow = compilePlanToWorkflow(plan, { + useMockAgents: true, + mockDelayMs: 10, + }); + + const events: PlanExecutionEvent[] = []; + const run = await workflow.createRun(); + const stream = await run.stream({ inputData: { context: {} } }); + + for await (const chunk of stream.fullStream) { + if (chunk.type.startsWith("data-plan-")) { + events.push(chunk as unknown as PlanExecutionEvent); + } + } + + const progressEvents = events.filter( + (e) => e.type === "data-plan-progress", + ); + + // Should have progress events after each depth + expect(progressEvents.length).toBeGreaterThan(0); + + // Last progress should show all steps complete + const lastProgress = progressEvents[progressEvents.length - 1]; + expect(lastProgress?.data.completedSteps).toBe(3); + expect(lastProgress?.data.totalSteps).toBe(3); + }, 10000); + + test("emits plan-complete event", async () => { + const plan = createMinimalPlan(); + const workflow = compilePlanToWorkflow(plan, { + useMockAgents: true, + mockDelayMs: 10, + }); + + const events: PlanExecutionEvent[] = []; + const run = await workflow.createRun(); + const stream = await run.stream({ inputData: { context: {} } }); + + for await (const chunk of stream.fullStream) { + if (chunk.type.startsWith("data-plan-")) { + events.push(chunk as unknown as PlanExecutionEvent); + } + } + + const completeEvent = events.find((e) => e.type === "data-plan-complete"); + expect(completeEvent).toBeDefined(); + expect(completeEvent?.data.planId).toBe("minimal-plan"); + expect(completeEvent?.data.success).toBe(true); + expect(completeEvent?.data.stepsCompleted).toBe(1); + expect(completeEvent?.data.stepsFailed).toBe(0); + }, 10000); +}); diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts new file mode 100644 index 00000000000..30464174c90 --- /dev/null +++ b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts @@ -0,0 +1,771 @@ +/** + * Plan Compiler — Transforms PlanSpec into Mastra Workflow + * + * Compiles a validated PlanSpec into an executable Mastra Workflow. + * Uses the TopologyAnalyzer to determine execution structure and creates + * steps with streaming instrumentation for real-time progress tracking. + * + * The compiler: + * - Analyzes plan topology for parallel groups and execution order + * - Creates Mastra steps with mock or real agent execution + * - Emits streaming events via writer.custom() for frontend consumption + * - Builds workflow using .then() and .parallel() based on dependencies + * + * @see docs/PLAN-task-decomposition.md for design documentation + */ + +import { createStep, createWorkflow } from "@mastra/core/workflows"; +import type { Step, Workflow } from "@mastra/core/workflows"; +import dedent from "dedent"; +import { z } from "zod"; + +import type { + DataContract, + Executor, + PlanSpec, + PlanStep, + StepType, +} from "../schemas/plan-spec"; +import type { MockAgent, MockResponse } from "./mock-agent"; +import { createMockAgentRegistry } from "./mock-agent"; +import { + analyzePlanTopology, + type ParallelGroup, + type TopologyAnalysis, +} from "./topology-analyzer"; + +// ============================================================================= +// STREAMING EVENT TYPES +// ============================================================================= + +/** + * Event emitted when plan execution starts. + */ +export interface PlanStartEvent { + type: "data-plan-start"; + data: { + planId: string; + goalSummary: string; + totalSteps: number; + criticalPathLength: number; + entryPoints: string[]; + parallelGroups: number; + }; +} + +/** + * Event emitted when a step begins execution. + */ +export interface PlanStepStartEvent { + type: "data-plan-step-start"; + data: { + stepId: string; + stepType: StepType; + description: string; + depth: number; + executor: Executor; + dependsOn: string[]; + }; +} + +/** + * Event emitted when a step completes successfully. + */ +export interface PlanStepCompleteEvent { + type: "data-plan-step-complete"; + data: { + stepId: string; + stepType: StepType; + durationMs: number; + outputSummary: string; + }; +} + +/** + * Event emitted when a step fails. + */ +export interface PlanStepErrorEvent { + type: "data-plan-step-error"; + data: { + stepId: string; + stepType: StepType; + error: string; + durationMs: number; + }; +} + +/** + * Event emitted to report overall progress. + */ +export interface PlanProgressEvent { + type: "data-plan-progress"; + data: { + completedSteps: number; + totalSteps: number; + currentDepth: number; + totalDepths: number; + }; +} + +/** + * Event emitted at depth level transitions. + */ +export interface PlanDepthTransitionEvent { + type: "data-plan-depth-transition"; + data: { + fromDepth: number; + toDepth: number; + stepsCompletedAtDepth: number; + stepsStartingAtDepth: number; + }; +} + +/** + * Event emitted when plan execution completes. + */ +export interface PlanCompleteEvent { + type: "data-plan-complete"; + data: { + planId: string; + success: boolean; + totalDurationMs: number; + stepsCompleted: number; + stepsFailed: number; + }; +} + +/** + * Union of all plan execution events. + */ +export type PlanExecutionEvent = + | PlanStartEvent + | PlanStepStartEvent + | PlanStepCompleteEvent + | PlanStepErrorEvent + | PlanProgressEvent + | PlanDepthTransitionEvent + | PlanCompleteEvent; + +// ============================================================================= +// COMPILER TYPES +// ============================================================================= + +/** + * Options for plan compilation. + */ +export interface CompilerOptions { + /** + * Use mock agents instead of real agents (for testing). + * @default true + */ + useMockAgents?: boolean; + + /** + * Simulated delay for mock agents in milliseconds. + * @default 100 + */ + mockDelayMs?: number; + + /** + * Agent registry for resolving executor refs. + * If not provided, uses mock registry when useMockAgents is true. + */ + agentRegistry?: Map; +} + +/** + * Context passed through compilation. + */ +interface CompilerContext { + plan: PlanSpec; + topology: TopologyAnalysis; + options: Required; + agentRegistry: Map; + steps: Map< + string, + Step< + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny + > + >; +} + +/** + * Input schema for compiled workflows. + */ +const compiledWorkflowInputSchema = z.object({ + /** Runtime context to pass to steps */ + context: z.record(z.unknown()).optional(), + /** Whether to emit streaming progress events */ + streamProgress: z.boolean().optional().default(true), +}); + +/** + * Output schema for compiled workflows. + */ +const compiledWorkflowOutputSchema = z.object({ + planId: z.string(), + success: z.boolean(), + results: z.record(z.unknown()), + errors: z + .array( + z.object({ + stepId: z.string(), + error: z.string(), + }), + ) + .optional(), + executionOrder: z.array(z.string()), + totalDurationMs: z.number(), +}); + +export type CompiledWorkflowInput = z.infer; +export type CompiledWorkflowOutput = z.infer< + typeof compiledWorkflowOutputSchema +>; + +// ============================================================================= +// MAIN COMPILER FUNCTION +// ============================================================================= + +/** + * Compiles a validated PlanSpec into a Mastra Workflow. + * + * The compilation strategy: + * 1. Analyze topology to get parallel groups and execution order + * 2. Create Mastra steps for each PlanStep with streaming instrumentation + * 3. Build workflow using parallel groups: + * - Single step at a depth → .then() + * - Multiple parallelizable steps at same depth → .parallel() + * + * @param plan - A validated PlanSpec (call validatePlan first!) + * @param options - Compilation options + * @returns Compiled Mastra workflow ready for execution + * + * @example + * ```typescript + * const plan = await generatePlan({ goal: "..." }); + * const validation = validatePlan(plan); + * if (!validation.valid) throw new Error("Invalid plan"); + * + * const workflow = compilePlanToWorkflow(plan, { useMockAgents: true }); + * const run = workflow.createRun(); + * const result = await run.start({ context: {} }); + * ``` + */ +export function compilePlanToWorkflow( + plan: PlanSpec, + options: CompilerOptions = {}, +): Workflow< + typeof compiledWorkflowInputSchema, + typeof compiledWorkflowOutputSchema, + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny +> { + // Normalize options + const normalizedOptions: Required = { + useMockAgents: options.useMockAgents ?? true, + mockDelayMs: options.mockDelayMs ?? 100, + agentRegistry: + options.agentRegistry ?? + createMockAgentRegistry({ simulatedDelayMs: options.mockDelayMs ?? 100 }), + }; + + // Analyze topology + const topology = analyzePlanTopology(plan); + + // Build compiler context + const ctx: CompilerContext = { + plan, + topology, + options: normalizedOptions, + agentRegistry: normalizedOptions.agentRegistry, + steps: new Map(), + }; + + // Phase 1: Create Mastra steps for each PlanStep + for (const planStep of plan.steps) { + const mastraStep = createMastraStep(planStep, ctx); + ctx.steps.set(planStep.id, mastraStep); + } + + // Phase 2: Create workflow + const workflow = createWorkflow({ + id: `compiled-plan-${plan.id}`, + inputSchema: compiledWorkflowInputSchema, + outputSchema: compiledWorkflowOutputSchema, + }); + + // Phase 3: Build workflow from parallel groups + buildWorkflowFromGroups(workflow, ctx); + + // Phase 4: Commit and return + workflow.commit(); + + return workflow; +} + +// ============================================================================= +// STEP CREATION +// ============================================================================= + +/** + * Creates a Mastra step from a PlanStep with streaming instrumentation. + */ +function createMastraStep( + planStep: PlanStep, + ctx: CompilerContext, +): Step< + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny +> { + const depth = ctx.topology.depthMap.get(planStep.id) ?? 0; + + // Build input/output schemas from data contracts + const inputSchema = buildInputSchema(planStep); + const outputSchema = buildOutputSchema(planStep); + + return createStep({ + id: planStep.id, + description: planStep.description, + inputSchema, + outputSchema, + execute: async ({ inputData, writer }) => { + const startTime = Date.now(); + + // Emit step start event + await writer?.custom({ + type: "data-plan-step-start", + data: { + stepId: planStep.id, + stepType: planStep.type, + description: planStep.description, + depth, + executor: planStep.executor, + dependsOn: planStep.dependsOn, + }, + } satisfies PlanStepStartEvent); + + try { + // Execute based on executor type + const result = await executeStep(planStep, inputData, ctx); + + const durationMs = Date.now() - startTime; + + // Emit step complete event + await writer?.custom({ + type: "data-plan-step-complete", + data: { + stepId: planStep.id, + stepType: planStep.type, + durationMs, + outputSummary: summarizeOutput(result), + }, + } satisfies PlanStepCompleteEvent); + + return { + stepId: planStep.id, + result, + durationMs, + }; + } catch (error) { + const durationMs = Date.now() - startTime; + + // Emit step error event + await writer?.custom({ + type: "data-plan-step-error", + data: { + stepId: planStep.id, + stepType: planStep.type, + error: error instanceof Error ? error.message : String(error), + durationMs, + }, + } satisfies PlanStepErrorEvent); + + // Re-throw for fail-fast behavior + throw error; + } + }, + }); +} + +/** + * Executes a step based on its executor binding. + */ +async function executeStep( + planStep: PlanStep, + inputData: unknown, + ctx: CompilerContext, +): Promise { + const { executor } = planStep; + + switch (executor.kind) { + case "agent": { + const agent = ctx.agentRegistry.get(executor.ref); + if (!agent) { + throw new Error( + `Agent "${executor.ref}" not found in registry. ` + + `Available agents: ${Array.from(ctx.agentRegistry.keys()).join(", ")}`, + ); + } + + // Build prompt from step configuration + const prompt = buildPromptForStep(planStep, inputData, ctx); + + // Execute via mock agent + const response = await agent.generate(prompt); + return response.object; + } + + case "tool": { + // Stub for future implementation + throw new Error( + `Tool executor not yet implemented. Step "${planStep.id}" uses tool "${executor.ref}".`, + ); + } + + case "workflow": { + // Stub for future implementation + throw new Error( + `Workflow executor not yet implemented. Step "${planStep.id}" uses workflow "${executor.ref}".`, + ); + } + + case "human": { + // Stub for future HITL implementation + throw new Error( + `Human executor not yet implemented. Step "${planStep.id}" requires human intervention. ` + + `Instructions: ${executor.instructions ?? "None provided"}`, + ); + } + + default: { + const exhaustiveCheck: never = executor; + throw new Error( + `Unknown executor kind: ${JSON.stringify(exhaustiveCheck)}`, + ); + } + } +} + +// ============================================================================= +// WORKFLOW FLOW BUILDING +// ============================================================================= + +/** + * Builds the workflow execution flow from parallel groups. + * + * Strategy: + * - Process parallel groups in order (by depth) + * - Single step at a depth → .then() + * - Multiple parallelizable steps → .parallel() + * - Wrap with entry/exit handlers for streaming events + */ +function buildWorkflowFromGroups( + workflow: Workflow< + typeof compiledWorkflowInputSchema, + typeof compiledWorkflowOutputSchema, + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny, + z.ZodTypeAny + >, + ctx: CompilerContext, +): void { + const { plan, topology } = ctx; + + // Track execution for final output + const executionState = { + startTime: 0, + completedStepIds: [] as string[], + results: {} as Record, + errors: [] as Array<{ stepId: string; error: string }>, + }; + + // Entry: Emit plan start event and initialize state + workflow.map(async ({ inputData, writer }) => { + executionState.startTime = Date.now(); + + await writer?.custom({ + type: "data-plan-start", + data: { + planId: plan.id, + goalSummary: plan.goalSummary, + totalSteps: plan.steps.length, + criticalPathLength: topology.criticalPath.length, + entryPoints: topology.entryPoints, + parallelGroups: topology.parallelGroups.length, + }, + } satisfies PlanStartEvent); + + return inputData; + }); + + // Process each parallel group + let previousDepth = -1; + + for (const group of topology.parallelGroups) { + const stepsInGroup = group.stepIds + .map((id) => ctx.steps.get(id)) + .filter((s): s is NonNullable => s !== undefined); + + if (stepsInGroup.length === 0) continue; + + // Emit depth transition event if depth changed + if (group.depth !== previousDepth && previousDepth >= 0) { + const fromDepth = previousDepth; + const toDepth = group.depth; + const stepsCompletedAtDepth = + topology.parallelGroups.find((g) => g.depth === fromDepth)?.stepIds + .length ?? 0; + + workflow.map(async ({ inputData, writer }) => { + await writer?.custom({ + type: "data-plan-depth-transition", + data: { + fromDepth, + toDepth, + stepsCompletedAtDepth, + stepsStartingAtDepth: stepsInGroup.length, + }, + } satisfies PlanDepthTransitionEvent); + + return inputData; + }); + } + + previousDepth = group.depth; + + // Add steps based on parallelizability + if (stepsInGroup.length === 1) { + // Single step - use .then() + workflow.then(stepsInGroup[0]!); + } else { + // Multiple steps - check if all are parallelizable + const parallelizableSteps = group.parallelizableStepIds + .map((id) => ctx.steps.get(id)) + .filter((s): s is NonNullable => s !== undefined); + + if (parallelizableSteps.length === stepsInGroup.length) { + // All parallelizable - use .parallel() + workflow.parallel(parallelizableSteps); + } else if (parallelizableSteps.length > 1) { + // Mixed: parallel first, then sequential + workflow.parallel(parallelizableSteps); + const sequentialSteps = stepsInGroup.filter( + (s) => !parallelizableSteps.includes(s), + ); + for (const step of sequentialSteps) { + workflow.then(step); + } + } else { + // All sequential + for (const step of stepsInGroup) { + workflow.then(step); + } + } + } + + // Emit progress after each group + const currentDepth = group.depth; + const completedAtThisPoint = topology.parallelGroups + .filter((g) => g.depth <= currentDepth) + .flatMap((g) => g.stepIds); + + workflow.map(async ({ inputData, writer }) => { + await writer?.custom({ + type: "data-plan-progress", + data: { + completedSteps: completedAtThisPoint.length, + totalSteps: plan.steps.length, + currentDepth, + totalDepths: topology.parallelGroups.length, + }, + } satisfies PlanProgressEvent); + + return inputData; + }); + } + + // Exit: Emit plan complete event and collect results + workflow.map(async ({ inputData, writer }) => { + const totalDurationMs = Date.now() - executionState.startTime; + + await writer?.custom({ + type: "data-plan-complete", + data: { + planId: plan.id, + success: executionState.errors.length === 0, + totalDurationMs, + stepsCompleted: plan.steps.length - executionState.errors.length, + stepsFailed: executionState.errors.length, + }, + } satisfies PlanCompleteEvent); + + return { + planId: plan.id, + success: executionState.errors.length === 0, + results: inputData as Record, + errors: + executionState.errors.length > 0 ? executionState.errors : undefined, + executionOrder: topology.topologicalOrder, + totalDurationMs, + }; + }); +} + +// ============================================================================= +// HELPER FUNCTIONS +// ============================================================================= + +/** + * Build input schema from step's data contracts. + */ +function buildInputSchema(planStep: PlanStep): z.ZodType { + if (planStep.inputs.length === 0) { + return z.object({}).passthrough(); + } + + const fields: Record> = {}; + for (const input of planStep.inputs) { + fields[input.name] = z.unknown().describe(input.description); + } + + return z.object(fields).passthrough(); +} + +/** + * Build output schema from step's data contracts. + */ +function buildOutputSchema(planStep: PlanStep): z.ZodType { + return z + .object({ + stepId: z.string(), + result: z.unknown(), + durationMs: z.number(), + }) + .passthrough(); +} + +/** + * Build a prompt for step execution based on step configuration. + */ +function buildPromptForStep( + planStep: PlanStep, + inputData: unknown, + ctx: CompilerContext, +): string { + const parts: string[] = []; + + parts.push(`## Task: ${planStep.description}`); + parts.push(`Step ID: ${planStep.id}`); + parts.push(""); + + // Add step-type specific context + switch (planStep.type) { + case "research": + parts.push(`Research Query: ${planStep.query}`); + parts.push(`Stopping Rule: ${planStep.stoppingRule}`); + break; + + case "synthesize": + parts.push(`Mode: ${planStep.mode}`); + parts.push(`Input Step IDs: ${planStep.inputStepIds.join(", ")}`); + if (planStep.mode === "evaluative" && planStep.evaluateAgainst) { + parts.push(`Evaluate Against: ${planStep.evaluateAgainst.join(", ")}`); + } + break; + + case "experiment": + parts.push(`Mode: ${planStep.mode}`); + parts.push(`Procedure: ${planStep.procedure}`); + parts.push(`Success Criteria: ${planStep.successCriteria.join(", ")}`); + // Reference hypotheses + const hypotheses = planStep.hypothesisIds + .map((id) => ctx.plan.hypotheses.find((h) => h.id === id)) + .filter((h): h is NonNullable => h !== undefined); + if (hypotheses.length > 0) { + parts.push(`Hypotheses to Test:`); + for (const h of hypotheses) { + parts.push(` - ${h.id}: ${h.statement}`); + } + } + break; + + case "develop": + parts.push(`Specification: ${planStep.specification}`); + parts.push(`Deliverables: ${planStep.deliverables.join(", ")}`); + break; + } + + // Add input data context if present + if ( + inputData && + typeof inputData === "object" && + Object.keys(inputData).length > 0 + ) { + parts.push(""); + parts.push("## Input Data"); + parts.push("```json"); + parts.push(JSON.stringify(inputData, null, 2)); + parts.push("```"); + } + + // Add evaluation criteria if present + if (planStep.evalCriteria) { + parts.push(""); + parts.push("## Success Criteria"); + parts.push(`Success: ${planStep.evalCriteria.successCondition}`); + if (planStep.evalCriteria.failureCondition) { + parts.push(`Failure: ${planStep.evalCriteria.failureCondition}`); + } + } + + return parts.join("\n"); +} + +/** + * Summarize output for streaming events. + */ +function summarizeOutput(result: unknown): string { + if (result === null || result === undefined) { + return ""; + } + + if (typeof result === "string") { + return result.slice(0, 200) + (result.length > 200 ? "..." : ""); + } + + if (typeof result === "object") { + // Check for mock response + if ("__mock" in result && result.__mock === true) { + const mock = result as MockResponse; + return `[Mock ${mock.stepType}] ${mock.stepId}`; + } + + const json = JSON.stringify(result); + return json.slice(0, 200) + (json.length > 200 ? "..." : ""); + } + + return String(result).slice(0, 200); +} + +// ============================================================================= +// EXPORTS +// ============================================================================= + +export { compiledWorkflowInputSchema, compiledWorkflowOutputSchema }; From 905fe84dbc48169ac2ad2c93e3ffbe8313854340 Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Thu, 18 Dec 2025 15:36:17 +0100 Subject: [PATCH 02/16] review, fixes and captures post phase 1 --- .../agent/plans/CONDITIONAL-BRANCHING.md | 207 +++++++ .../src/mastra/tools/mock-agent.ts | 11 +- .../src/mastra/tools/plan-compiler.test.ts | 444 +++++++++++++- .../src/mastra/tools/plan-compiler.ts | 571 +++++++++--------- 4 files changed, 912 insertions(+), 321 deletions(-) create mode 100644 apps/hash-ai-agent/agent/plans/CONDITIONAL-BRANCHING.md diff --git a/apps/hash-ai-agent/agent/plans/CONDITIONAL-BRANCHING.md b/apps/hash-ai-agent/agent/plans/CONDITIONAL-BRANCHING.md new file mode 100644 index 00000000000..1b0887a8b2c --- /dev/null +++ b/apps/hash-ai-agent/agent/plans/CONDITIONAL-BRANCHING.md @@ -0,0 +1,207 @@ +# Conditional Branching in Plan Execution + +> **Status**: Deferred to Phase 4 +> **Created**: 2024-12-18 +> **Context**: Plan compilation and execution infrastructure + +## Overview + +Conditional branching allows plan execution to take different paths based on +runtime evaluation results. This is essential for: + +- **Evaluation → retry cycles**: When synthesis/evaluation step determines quality is insufficient +- **Quality gates**: Pass/fail/escalate decisions at key checkpoints +- **Human-in-the-loop decision points**: Routing to human review when confidence is low +- **Adaptive execution**: Choosing different strategies based on intermediate results + +## Current State + +The plan compiler (`plan-compiler.ts`) currently supports: + +- Linear execution (`.then()`) +- Parallel execution (`.parallel()`) +- Fan-in patterns (multiple steps → single synthesis) +- Fan-out patterns (single step → multiple parallel steps) + +**Not yet supported**: + +- Conditional branching (`.branch()`) +- Loop constructs (`.dowhile()`, `.dountil()`) + +## Mastra Primitive + +Mastra workflows support conditional branching via `.branch()`: + +```typescript +workflow.branch([ + [async ({ inputData }) => inputData.decision === "retry", retryStep], + [async ({ inputData }) => inputData.decision === "pass", continueStep], + [async ({ inputData }) => true, fallbackStep], // default case +]); +``` + +The condition functions receive the output of the previous step and return a boolean. +The first matching condition determines which branch is taken. + +## PlanSpec Extension Options + +### Option A: Explicit Conditional Edges + +Add a `conditionalEdges` array to PlanSpec with serializable condition specs: + +```typescript +interface ConditionSpec { + field: string; // Path in previous step output, e.g., "decision" + operator: "eq" | "neq" | "gt" | "lt" | "in" | "contains"; + value: unknown; // Value to compare against +} + +interface ConditionalEdge { + id: string; + fromStepId: string; // Source step (typically an evaluation step) + conditions: Array<{ + condition: ConditionSpec; + toStepId: string; // Target step if condition matches + }>; + defaultStepId?: string; // Fallback if no condition matches +} + +// In PlanSpec: +interface PlanSpec { + // ... existing fields ... + conditionalEdges?: ConditionalEdge[]; +} +``` + +**Pros**: + +- Explicit and declarative +- Easy to validate statically +- Clear visualization in UI + +**Cons**: + +- Adds complexity to PlanSpec schema +- Condition language is limited (no arbitrary expressions) + +### Option B: Gateway Steps + +Use evaluation steps that output decisions, followed by a special "gateway" step type: + +```typescript +interface GatewayStep { + type: "gateway"; + id: string; + dependsOn: [string]; // Must depend on exactly one step + routes: Array<{ + condition: ConditionSpec; + toStepId: string; + }>; + defaultRoute?: string; +} +``` + +**Pros**: + +- Gateway is a first-class step type +- Clearer semantic meaning +- Easier to reason about in isolation + +**Cons**: + +- More verbose plans +- Gateway steps don't "do" anything (just routing) + +### Option C: Inline Conditions on dependsOn + +Extend `dependsOn` to optionally include conditions: + +```typescript +interface ConditionalDependency { + stepId: string; + condition?: ConditionSpec; // Only proceed if condition matches +} + +// In PlanStep: +dependsOn: Array; +``` + +**Pros**: + +- Minimal schema changes +- Natural extension of existing pattern + +**Cons**: + +- Makes dependency analysis more complex +- Harder to visualize + +## Relationship to Decision Points + +Earlier discussion identified the need for plans to surface uncertainty: + +- Assumptions +- Missing inputs +- Clarifying questions +- Risks / decision points + +These are currently tracked in `unknownsMap` as metadata. Decision points for +conditional branching could be: + +| Decision Type | How It Maps to Branching | +| --------------- | ---------------------------------------------- | +| `clarification` | Branch to HITL step for user input | +| `assumption` | Branch based on assumption validation | +| `risk` | Branch to mitigation path if risk materializes | +| `tradeoff` | Branch based on user preference or heuristic | + +The relationship between `unknownsMap` and conditional edges needs further design: + +- Should decision points automatically generate conditional edges? +- Or should they remain separate (metadata vs control flow)? + +**Tracked for future**: Clarify this relationship when implementing Phase 4. + +## Security Considerations + +Condition evaluation must be carefully constrained: + +1. **No arbitrary code execution**: Conditions must be declarative, not executable JS +2. **Limited operators**: Only safe comparison operators +3. **Field path validation**: Ensure field paths don't access sensitive data +4. **Timeout protection**: Condition evaluation should be bounded + +## Deferred Because + +1. **Current focus**: Phase 1-3 focus on basic DAG execution with streaming +2. **Schema design**: Need to finalize which option (A, B, or C) to pursue +3. **Validation complexity**: Conditional edges require additional validation: + - All branches must be reachable + - No orphaned steps after conditions + - Conditions must be evaluable given step outputs +4. **UI implications**: Conditional branches need visualization support + +## Implementation Plan (Phase 4) + +When we return to this: + +1. **Design decision**: Choose between Option A, B, or C (likely A) +2. **Schema extension**: Add conditional edges to PlanSpec +3. **Validation**: Extend plan-validator.ts for conditional edge checks +4. **Compiler**: Implement `.branch()` generation from conditional edges +5. **Tests**: Add conditional branching test fixtures +6. **Topology**: Update topology-analyzer.ts to handle conditional paths +7. **Streaming**: Emit events for branch decisions + +## Related Files + +- `src/mastra/tools/plan-compiler.ts` - Main compiler (needs `.branch()` support) +- `src/mastra/schemas/plan-spec.ts` - Schema (needs conditional edge types) +- `src/mastra/tools/plan-validator.ts` - Validation (needs edge validation) +- `src/mastra/tools/topology-analyzer.ts` - Analysis (needs conditional path handling) + +## References + +- Mastra workflow `.branch()` documentation +- Earlier conversation about decision points and surfaced uncertainty +- XState/Stately statechart patterns (for future consideration) diff --git a/apps/hash-ai-agent/src/mastra/tools/mock-agent.ts b/apps/hash-ai-agent/src/mastra/tools/mock-agent.ts index 9e8433a2359..c9febd70815 100644 --- a/apps/hash-ai-agent/src/mastra/tools/mock-agent.ts +++ b/apps/hash-ai-agent/src/mastra/tools/mock-agent.ts @@ -157,6 +157,13 @@ export class MockAgent { await this.delay(this.simulatedDelayMs); } + // Check for __THROW__ pattern to simulate step failures + if (prompt.includes("__THROW__")) { + throw new Error( + "Simulated step failure: __THROW__ pattern detected in prompt", + ); + } + // Extract step info from prompt const stepInfo = this.extractStepInfo(prompt); @@ -368,7 +375,9 @@ export class MockAgent { * Delay helper for simulating processing time. */ private delay(ms: number): Promise { - return new Promise((resolve) => setTimeout(resolve, ms)); + return new Promise((resolve) => { + setTimeout(resolve, ms); + }); } } diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts index 6486c4974a1..8f5c4036958 100644 --- a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts +++ b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts @@ -14,11 +14,11 @@ import { describe, expect, test } from "vitest"; import type { PlanSpec } from "../schemas/plan-spec"; -import { validatePlan } from "./plan-validator"; import { compilePlanToWorkflow, type PlanExecutionEvent, } from "./plan-compiler"; +import { validatePlan } from "./plan-validator"; import { analyzePlanTopology } from "./topology-analyzer"; // ============================================================================= @@ -375,6 +375,243 @@ function createMixedParallelismPlan(): PlanSpec { }; } +/** + * Creates a deep DAG plan with 5 depth levels and multiple fan-in/fan-out. + * + * S1 (research) depth 0 + * / | \ + * S2 S3 S4 (research) depth 1, parallel + * \ | / + * S5 (synthesize) depth 2, fan-in + * / \ + * S6 S7 (develop) depth 3, parallel + * \ / + * S8 (synthesize) depth 4, final evaluation + */ +function createDeepDagPlan(): PlanSpec { + return { + id: "deep-dag-plan", + goalSummary: "Deep DAG with multiple fan-in/fan-out patterns", + requirements: [ + { id: "R1", description: "Research phase", priority: "must" }, + { id: "R2", description: "Synthesis phase", priority: "must" }, + { id: "R3", description: "Development phase", priority: "must" }, + ], + hypotheses: [], + steps: [ + // Depth 0: Initial research + { + type: "research", + id: "S1", + description: "Initial exploration of the problem space", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [ + { name: "initial_findings", description: "Initial findings" }, + ], + query: "Explore problem space", + stoppingRule: "Identify 3 key areas", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + // Depth 1: Parallel deep-dives + { + type: "research", + id: "S2", + description: "Deep dive into area A", + dependsOn: ["S1"], + requirementIds: ["R1"], + inputs: [{ name: "context", description: "From S1", fromStepId: "S1" }], + outputs: [{ name: "area_a_findings", description: "Area A findings" }], + query: "Research area A in depth", + stoppingRule: "Find 5 relevant sources", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "research", + id: "S3", + description: "Deep dive into area B", + dependsOn: ["S1"], + requirementIds: ["R1"], + inputs: [{ name: "context", description: "From S1", fromStepId: "S1" }], + outputs: [{ name: "area_b_findings", description: "Area B findings" }], + query: "Research area B in depth", + stoppingRule: "Find 5 relevant sources", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "research", + id: "S4", + description: "Deep dive into area C", + dependsOn: ["S1"], + requirementIds: ["R1"], + inputs: [{ name: "context", description: "From S1", fromStepId: "S1" }], + outputs: [{ name: "area_c_findings", description: "Area C findings" }], + query: "Research area C in depth", + stoppingRule: "Find 5 relevant sources", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + // Depth 2: Synthesis fan-in + { + type: "synthesize", + id: "S5", + description: "Combine findings from all research areas", + dependsOn: ["S2", "S3", "S4"], + requirementIds: ["R2"], + inputs: [ + { name: "area_a", description: "From S2", fromStepId: "S2" }, + { name: "area_b", description: "From S3", fromStepId: "S3" }, + { name: "area_c", description: "From S4", fromStepId: "S4" }, + ], + outputs: [{ name: "synthesis", description: "Combined synthesis" }], + mode: "integrative", + inputStepIds: ["S2", "S3", "S4"], + parallelizable: false, + executor: { kind: "agent", ref: "result-synthesizer" }, + }, + // Depth 3: Parallel development + { + type: "develop", + id: "S6", + description: "Develop component X based on synthesis", + dependsOn: ["S5"], + requirementIds: ["R3"], + inputs: [ + { name: "synthesis", description: "From S5", fromStepId: "S5" }, + ], + outputs: [{ name: "component_x", description: "Component X" }], + specification: "Build component X", + deliverables: ["Component X implementation"], + parallelizable: true, + executor: { kind: "agent", ref: "code-writer" }, + }, + { + type: "develop", + id: "S7", + description: "Develop component Y based on synthesis", + dependsOn: ["S5"], + requirementIds: ["R3"], + inputs: [ + { name: "synthesis", description: "From S5", fromStepId: "S5" }, + ], + outputs: [{ name: "component_y", description: "Component Y" }], + specification: "Build component Y", + deliverables: ["Component Y implementation"], + parallelizable: true, + executor: { kind: "agent", ref: "code-writer" }, + }, + // Depth 4: Final synthesis/evaluation + { + type: "synthesize", + id: "S8", + description: "Evaluate and combine both components", + dependsOn: ["S6", "S7"], + requirementIds: ["R2", "R3"], + inputs: [ + { name: "component_x", description: "From S6", fromStepId: "S6" }, + { name: "component_y", description: "From S7", fromStepId: "S7" }, + ], + outputs: [ + { name: "final_evaluation", description: "Final evaluation" }, + ], + mode: "evaluative", + inputStepIds: ["S6", "S7"], + evaluateAgainst: [ + "Do components integrate correctly?", + "Are requirements met?", + ], + parallelizable: false, + executor: { kind: "agent", ref: "progress-evaluator" }, + }, + ], + unknownsMap: { + knownKnowns: ["DAG structure is valid", "All step types are supported"], + knownUnknowns: ["Optimal parallelization", "Integration complexity"], + unknownUnknowns: [ + { + potentialSurprise: "Unexpected dependencies between areas", + detectionSignal: "Synthesis step fails to integrate", + }, + ], + communityCheck: "Review DAG structure and data flow", + }, + }; +} + +/** + * Creates a plan with an invalid executor reference for error testing. + */ +function createPlanWithInvalidExecutor(): PlanSpec { + return { + id: "invalid-executor-plan", + goalSummary: "Plan with invalid executor reference", + requirements: [ + { id: "R1", description: "Test requirement", priority: "must" }, + ], + hypotheses: [], + steps: [ + { + type: "research", + id: "S1", + description: "Step with nonexistent executor", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [{ name: "findings", description: "Findings" }], + query: "Test query", + stoppingRule: "Find sources", + parallelizable: true, + executor: { kind: "agent", ref: "nonexistent-agent" }, // Invalid! + }, + ], + unknownsMap: { + knownKnowns: [], + knownUnknowns: [], + unknownUnknowns: [], + communityCheck: "", + }, + }; +} + +/** + * Creates a plan where a step will throw an error (via __THROW__ in description). + */ +function createPlanWithThrowingStep(): PlanSpec { + return { + id: "throwing-step-plan", + goalSummary: "Plan where a step throws an error", + requirements: [ + { id: "R1", description: "Test requirement", priority: "must" }, + ], + hypotheses: [], + steps: [ + { + type: "research", + id: "S1", + description: "__THROW__ This step should fail", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [{ name: "findings", description: "Findings" }], + query: "__THROW__ trigger error", + stoppingRule: "Find sources", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + ], + unknownsMap: { + knownKnowns: [], + knownUnknowns: [], + unknownUnknowns: [], + communityCheck: "", + }, + }; +} + // ============================================================================= // COMPILATION TESTS // ============================================================================= @@ -433,6 +670,16 @@ describe("Plan Compiler — Compilation", () => { const workflow = compilePlanToWorkflow(plan, { useMockAgents: true }); expect(workflow).toBeDefined(); }); + + test("compiles a deep DAG plan with 5 depth levels", () => { + const plan = createDeepDagPlan(); + + const validation = validatePlan(plan); + expect(validation.valid).toBe(true); + + const workflow = compilePlanToWorkflow(plan, { useMockAgents: true }); + expect(workflow).toBeDefined(); + }); }); }); @@ -469,8 +716,8 @@ describe("Plan Compiler — Topology Analysis", () => { // Depth 1: S4 expect(topology.parallelGroups.length).toBe(2); - const depth0 = topology.parallelGroups.find((g) => g.depth === 0); - const depth1 = topology.parallelGroups.find((g) => g.depth === 1); + const depth0 = topology.parallelGroups.find((grp) => grp.depth === 0); + const depth1 = topology.parallelGroups.find((grp) => grp.depth === 1); expect(depth0?.stepIds).toHaveLength(3); expect(depth0?.stepIds).toContain("S1"); @@ -491,9 +738,9 @@ describe("Plan Compiler — Topology Analysis", () => { // Depth 2: S4 expect(topology.parallelGroups.length).toBe(3); - const depth0 = topology.parallelGroups.find((g) => g.depth === 0); - const depth1 = topology.parallelGroups.find((g) => g.depth === 1); - const depth2 = topology.parallelGroups.find((g) => g.depth === 2); + const depth0 = topology.parallelGroups.find((grp) => grp.depth === 0); + const depth1 = topology.parallelGroups.find((grp) => grp.depth === 1); + const depth2 = topology.parallelGroups.find((grp) => grp.depth === 2); expect(depth0?.stepIds).toEqual(["S1"]); expect(depth1?.stepIds).toHaveLength(2); @@ -524,12 +771,60 @@ describe("Plan Compiler — Topology Analysis", () => { const plan = createMixedParallelismPlan(); const topology = analyzePlanTopology(plan); - const depth0 = topology.parallelGroups.find((g) => g.depth === 0); + const depth0 = topology.parallelGroups.find((grp) => grp.depth === 0); // S1 is parallelizable, S2 is not expect(depth0?.parallelizableStepIds).toContain("S1"); expect(depth0?.parallelizableStepIds).not.toContain("S2"); }); + + test("correctly computes 5 depth levels for deep DAG", () => { + const plan = createDeepDagPlan(); + const topology = analyzePlanTopology(plan); + + // Should have 5 parallel groups (depths 0-4) + expect(topology.parallelGroups.length).toBe(5); + + // Verify each depth level + const depth0 = topology.parallelGroups.find((grp) => grp.depth === 0); + const depth1 = topology.parallelGroups.find((grp) => grp.depth === 1); + const depth2 = topology.parallelGroups.find((grp) => grp.depth === 2); + const depth3 = topology.parallelGroups.find((grp) => grp.depth === 3); + const depth4 = topology.parallelGroups.find((grp) => grp.depth === 4); + + expect(depth0?.stepIds).toEqual(["S1"]); + expect(depth1?.stepIds).toHaveLength(3); + expect(depth1?.stepIds).toContain("S2"); + expect(depth1?.stepIds).toContain("S3"); + expect(depth1?.stepIds).toContain("S4"); + expect(depth2?.stepIds).toEqual(["S5"]); + expect(depth3?.stepIds).toHaveLength(2); + expect(depth3?.stepIds).toContain("S6"); + expect(depth3?.stepIds).toContain("S7"); + expect(depth4?.stepIds).toEqual(["S8"]); + }); + + test("correctly identifies fan-in points in deep DAG", () => { + const plan = createDeepDagPlan(); + const topology = analyzePlanTopology(plan); + + // S5 is a fan-in (depends on S2, S3, S4) + // S8 is a fan-in (depends on S6, S7) + // These should have higher dependent counts in predecessor steps + + // Entry point is S1 + expect(topology.entryPoints).toEqual(["S1"]); + + // Exit point is S8 + expect(topology.exitPoints).toEqual(["S8"]); + + // Check that fan-in steps are at correct depths + const depth2 = topology.parallelGroups.find((grp) => grp.depth === 2); + const depth4 = topology.parallelGroups.find((grp) => grp.depth === 4); + + expect(depth2?.stepIds).toContain("S5"); // Fan-in from S2, S3, S4 + expect(depth4?.stepIds).toContain("S8"); // Fan-in from S6, S7 + }); }); // ============================================================================= @@ -586,7 +881,7 @@ describe("Plan Compiler — Execution", () => { if (result.status === "success") { expect(result.result.success).toBe(true); // S4 should be last (depends on S1, S2, S3) - const order = result.result.executionOrder as string[]; + const order = result.result.executionOrder; expect(order[order.length - 1]).toBe("S4"); } }, 10000); @@ -604,7 +899,7 @@ describe("Plan Compiler — Execution", () => { expect(result.status).toBe("success"); if (result.status === "success") { expect(result.result.success).toBe(true); - const order = result.result.executionOrder as string[]; + const order = result.result.executionOrder; // S1 should be first expect(order[0]).toBe("S1"); @@ -619,6 +914,54 @@ describe("Plan Compiler — Execution", () => { expect(s3Index).toBeLessThan(order.length - 1); } }, 10000); + + test("executes deep DAG respecting all dependencies", async () => { + const plan = createDeepDagPlan(); + const workflow = compilePlanToWorkflow(plan, { + useMockAgents: true, + mockDelayMs: 10, + }); + + const run = await workflow.createRun(); + const result = await run.start({ inputData: { context: {} } }); + + expect(result.status).toBe("success"); + if (result.status === "success") { + expect(result.result.success).toBe(true); + const order = result.result.executionOrder; + + // Verify execution order respects dependencies + // S1 must be first + expect(order[0]).toBe("S1"); + + // S8 must be last + expect(order[order.length - 1]).toBe("S8"); + + // S2, S3, S4 must come after S1 and before S5 + const s1Index = order.indexOf("S1"); + const s2Index = order.indexOf("S2"); + const s3Index = order.indexOf("S3"); + const s4Index = order.indexOf("S4"); + const s5Index = order.indexOf("S5"); + + expect(s2Index).toBeGreaterThan(s1Index); + expect(s3Index).toBeGreaterThan(s1Index); + expect(s4Index).toBeGreaterThan(s1Index); + expect(s5Index).toBeGreaterThan(s2Index); + expect(s5Index).toBeGreaterThan(s3Index); + expect(s5Index).toBeGreaterThan(s4Index); + + // S6, S7 must come after S5 and before S8 + const s6Index = order.indexOf("S6"); + const s7Index = order.indexOf("S7"); + const s8Index = order.indexOf("S8"); + + expect(s6Index).toBeGreaterThan(s5Index); + expect(s7Index).toBeGreaterThan(s5Index); + expect(s8Index).toBeGreaterThan(s6Index); + expect(s8Index).toBeGreaterThan(s7Index); + } + }, 15000); }); // ============================================================================= @@ -637,7 +980,7 @@ describe("Plan Compiler — Streaming Events", () => { const run = await workflow.createRun(); // Use stream to capture events - const stream = await run.stream({ inputData: { context: {} } }); + const stream = run.stream({ inputData: { context: {} } }); for await (const chunk of stream.fullStream) { if (chunk.type.startsWith("data-plan-")) { @@ -645,7 +988,7 @@ describe("Plan Compiler — Streaming Events", () => { } } - const startEvent = events.find((e) => e.type === "data-plan-start"); + const startEvent = events.find((evt) => evt.type === "data-plan-start"); expect(startEvent).toBeDefined(); expect(startEvent?.data.planId).toBe("minimal-plan"); expect(startEvent?.data.totalSteps).toBe(1); @@ -660,7 +1003,7 @@ describe("Plan Compiler — Streaming Events", () => { const events: PlanExecutionEvent[] = []; const run = await workflow.createRun(); - const stream = await run.stream({ inputData: { context: {} } }); + const stream = run.stream({ inputData: { context: {} } }); for await (const chunk of stream.fullStream) { if (chunk.type.startsWith("data-plan-")) { @@ -669,10 +1012,10 @@ describe("Plan Compiler — Streaming Events", () => { } const stepStartEvents = events.filter( - (e) => e.type === "data-plan-step-start", + (evt) => evt.type === "data-plan-step-start", ); const stepCompleteEvents = events.filter( - (e) => e.type === "data-plan-step-complete", + (evt) => evt.type === "data-plan-step-complete", ); expect(stepStartEvents).toHaveLength(1); @@ -691,7 +1034,7 @@ describe("Plan Compiler — Streaming Events", () => { const events: PlanExecutionEvent[] = []; const run = await workflow.createRun(); - const stream = await run.stream({ inputData: { context: {} } }); + const stream = run.stream({ inputData: { context: {} } }); for await (const chunk of stream.fullStream) { if (chunk.type.startsWith("data-plan-")) { @@ -700,7 +1043,7 @@ describe("Plan Compiler — Streaming Events", () => { } const progressEvents = events.filter( - (e) => e.type === "data-plan-progress", + (evt) => evt.type === "data-plan-progress", ); // Should have progress events after each depth @@ -721,7 +1064,7 @@ describe("Plan Compiler — Streaming Events", () => { const events: PlanExecutionEvent[] = []; const run = await workflow.createRun(); - const stream = await run.stream({ inputData: { context: {} } }); + const stream = run.stream({ inputData: { context: {} } }); for await (const chunk of stream.fullStream) { if (chunk.type.startsWith("data-plan-")) { @@ -729,7 +1072,9 @@ describe("Plan Compiler — Streaming Events", () => { } } - const completeEvent = events.find((e) => e.type === "data-plan-complete"); + const completeEvent = events.find( + (evt) => evt.type === "data-plan-complete", + ); expect(completeEvent).toBeDefined(); expect(completeEvent?.data.planId).toBe("minimal-plan"); expect(completeEvent?.data.success).toBe(true); @@ -737,3 +1082,66 @@ describe("Plan Compiler — Streaming Events", () => { expect(completeEvent?.data.stepsFailed).toBe(0); }, 10000); }); + +// ============================================================================= +// ERROR HANDLING TESTS +// ============================================================================= + +describe("Plan Compiler — Error Handling", () => { + test("throws when executor ref not found in registry", async () => { + const plan = createPlanWithInvalidExecutor(); + const workflow = compilePlanToWorkflow(plan, { + useMockAgents: true, + mockDelayMs: 10, + }); + + const run = await workflow.createRun(); + const result = await run.start({ inputData: { context: {} } }); + + // Workflow should fail due to missing executor + expect(result.status).toBe("failed"); + }, 10000); + + test("emits step-error event when step execution fails", async () => { + const plan = createPlanWithThrowingStep(); + const workflow = compilePlanToWorkflow(plan, { + useMockAgents: true, + mockDelayMs: 10, + }); + + const events: PlanExecutionEvent[] = []; + const run = await workflow.createRun(); + const stream = run.stream({ inputData: { context: {} } }); + + for await (const chunk of stream.fullStream) { + if (chunk.type.startsWith("data-plan-")) { + events.push(chunk as unknown as PlanExecutionEvent); + } + } + + // Should have emitted a step-error event + const errorEvents = events.filter( + (evt) => evt.type === "data-plan-step-error", + ); + expect(errorEvents.length).toBeGreaterThan(0); + + // Error event should contain the step ID and error message + const errorEvent = errorEvents[0]; + expect(errorEvent?.data.stepId).toBe("S1"); + expect(errorEvent?.data.error).toContain("__THROW__"); + }, 10000); + + test("workflow status is failed when step throws", async () => { + const plan = createPlanWithThrowingStep(); + const workflow = compilePlanToWorkflow(plan, { + useMockAgents: true, + mockDelayMs: 10, + }); + + const run = await workflow.createRun(); + const result = await run.start({ inputData: { context: {} } }); + + // Workflow should have failed status + expect(result.status).toBe("failed"); + }, 10000); +}); diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts index 30464174c90..11f219a0a96 100644 --- a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts +++ b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts @@ -14,13 +14,11 @@ * @see docs/PLAN-task-decomposition.md for design documentation */ -import { createStep, createWorkflow } from "@mastra/core/workflows"; import type { Step, Workflow } from "@mastra/core/workflows"; -import dedent from "dedent"; +import { createStep, createWorkflow } from "@mastra/core/workflows"; import { z } from "zod"; import type { - DataContract, Executor, PlanSpec, PlanStep, @@ -30,7 +28,6 @@ import type { MockAgent, MockResponse } from "./mock-agent"; import { createMockAgentRegistry } from "./mock-agent"; import { analyzePlanTopology, - type ParallelGroup, type TopologyAnalysis, } from "./topology-analyzer"; @@ -181,18 +178,8 @@ interface CompilerContext { topology: TopologyAnalysis; options: Required; agentRegistry: Map; - steps: Map< - string, - Step< - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny - > - >; + // eslint-disable-next-line @typescript-eslint/no-explicit-any + steps: Map>; } /** @@ -200,7 +187,7 @@ interface CompilerContext { */ const compiledWorkflowInputSchema = z.object({ /** Runtime context to pass to steps */ - context: z.record(z.unknown()).optional(), + context: z.record(z.string(), z.unknown()).optional(), /** Whether to emit streaming progress events */ streamProgress: z.boolean().optional().default(true), }); @@ -211,7 +198,7 @@ const compiledWorkflowInputSchema = z.object({ const compiledWorkflowOutputSchema = z.object({ planId: z.string(), success: z.boolean(), - results: z.record(z.unknown()), + results: z.record(z.string(), z.unknown()), errors: z .array( z.object({ @@ -230,87 +217,199 @@ export type CompiledWorkflowOutput = z.infer< >; // ============================================================================= -// MAIN COMPILER FUNCTION +// HELPER FUNCTIONS (defined first to avoid no-use-before-define) // ============================================================================= /** - * Compiles a validated PlanSpec into a Mastra Workflow. - * - * The compilation strategy: - * 1. Analyze topology to get parallel groups and execution order - * 2. Create Mastra steps for each PlanStep with streaming instrumentation - * 3. Build workflow using parallel groups: - * - Single step at a depth → .then() - * - Multiple parallelizable steps at same depth → .parallel() - * - * @param plan - A validated PlanSpec (call validatePlan first!) - * @param options - Compilation options - * @returns Compiled Mastra workflow ready for execution - * - * @example - * ```typescript - * const plan = await generatePlan({ goal: "..." }); - * const validation = validatePlan(plan); - * if (!validation.valid) throw new Error("Invalid plan"); - * - * const workflow = compilePlanToWorkflow(plan, { useMockAgents: true }); - * const run = workflow.createRun(); - * const result = await run.start({ context: {} }); - * ``` + * Build input schema from step's data contracts. */ -export function compilePlanToWorkflow( - plan: PlanSpec, - options: CompilerOptions = {}, -): Workflow< - typeof compiledWorkflowInputSchema, - typeof compiledWorkflowOutputSchema, - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny -> { - // Normalize options - const normalizedOptions: Required = { - useMockAgents: options.useMockAgents ?? true, - mockDelayMs: options.mockDelayMs ?? 100, - agentRegistry: - options.agentRegistry ?? - createMockAgentRegistry({ simulatedDelayMs: options.mockDelayMs ?? 100 }), - }; +function buildInputSchema(planStep: PlanStep): z.ZodType { + if (planStep.inputs.length === 0) { + return z.object({}).passthrough(); + } - // Analyze topology - const topology = analyzePlanTopology(plan); + const fields: Record> = {}; + for (const input of planStep.inputs) { + fields[input.name] = z.unknown().describe(input.description); + } - // Build compiler context - const ctx: CompilerContext = { - plan, - topology, - options: normalizedOptions, - agentRegistry: normalizedOptions.agentRegistry, - steps: new Map(), - }; + return z.object(fields).passthrough(); +} - // Phase 1: Create Mastra steps for each PlanStep - for (const planStep of plan.steps) { - const mastraStep = createMastraStep(planStep, ctx); - ctx.steps.set(planStep.id, mastraStep); +/** + * Build output schema from step's data contracts. + */ +function buildOutputSchema(_planStep: PlanStep): z.ZodType { + return z + .object({ + stepId: z.string(), + result: z.unknown(), + durationMs: z.number(), + }) + .passthrough(); +} + +/** + * Build a prompt for step execution based on step configuration. + */ +function buildPromptForStep( + planStep: PlanStep, + inputData: unknown, + ctx: CompilerContext, +): string { + const parts: string[] = []; + + parts.push(`## Task: ${planStep.description}`); + parts.push(`Step ID: ${planStep.id}`); + parts.push(""); + + // Add step-type specific context + switch (planStep.type) { + case "research": + parts.push(`Research Query: ${planStep.query}`); + parts.push(`Stopping Rule: ${planStep.stoppingRule}`); + break; + + case "synthesize": + parts.push(`Mode: ${planStep.mode}`); + parts.push(`Input Step IDs: ${planStep.inputStepIds.join(", ")}`); + if (planStep.mode === "evaluative" && planStep.evaluateAgainst) { + parts.push(`Evaluate Against: ${planStep.evaluateAgainst.join(", ")}`); + } + break; + + case "experiment": { + parts.push(`Mode: ${planStep.mode}`); + parts.push(`Procedure: ${planStep.procedure}`); + parts.push(`Success Criteria: ${planStep.successCriteria.join(", ")}`); + // Reference hypotheses + const hypotheses = planStep.hypothesisIds + .map((id) => ctx.plan.hypotheses.find((hyp) => hyp.id === id)) + .filter((hyp): hyp is NonNullable => hyp !== undefined); + if (hypotheses.length > 0) { + parts.push(`Hypotheses to Test:`); + for (const hyp of hypotheses) { + parts.push(` - ${hyp.id}: ${hyp.statement}`); + } + } + break; + } + + case "develop": + parts.push(`Specification: ${planStep.specification}`); + parts.push(`Deliverables: ${planStep.deliverables.join(", ")}`); + break; } - // Phase 2: Create workflow - const workflow = createWorkflow({ - id: `compiled-plan-${plan.id}`, - inputSchema: compiledWorkflowInputSchema, - outputSchema: compiledWorkflowOutputSchema, - }); + // Add input data context if present + if ( + inputData && + typeof inputData === "object" && + Object.keys(inputData).length > 0 + ) { + parts.push(""); + parts.push("## Input Data"); + parts.push("```json"); + parts.push(JSON.stringify(inputData, null, 2)); + parts.push("```"); + } - // Phase 3: Build workflow from parallel groups - buildWorkflowFromGroups(workflow, ctx); + // Add evaluation criteria if present + if (planStep.evalCriteria) { + parts.push(""); + parts.push("## Success Criteria"); + parts.push(`Success: ${planStep.evalCriteria.successCondition}`); + if (planStep.evalCriteria.failureCondition) { + parts.push(`Failure: ${planStep.evalCriteria.failureCondition}`); + } + } - // Phase 4: Commit and return - workflow.commit(); + return parts.join("\n"); +} - return workflow; +/** + * Summarize output for streaming events. + */ +function summarizeOutput(result: unknown): string { + if (result === null || result === undefined) { + return ""; + } + + if (typeof result === "string") { + return result.slice(0, 200) + (result.length > 200 ? "..." : ""); + } + + if (typeof result === "object") { + // Check for mock response + if ("__mock" in result && result.__mock === true) { + const mock = result as MockResponse; + return `[Mock ${mock.stepType}] ${mock.stepId}`; + } + + const json = JSON.stringify(result); + return json.slice(0, 200) + (json.length > 200 ? "..." : ""); + } + + return JSON.stringify(result).slice(0, 200); +} + +/** + * Executes a step based on its executor binding. + */ +async function executeStep( + planStep: PlanStep, + inputData: unknown, + ctx: CompilerContext, +): Promise { + const { executor } = planStep; + + switch (executor.kind) { + case "agent": { + const agent = ctx.agentRegistry.get(executor.ref); + if (!agent) { + throw new Error( + `Agent "${executor.ref}" not found in registry. ` + + `Available agents: ${Array.from(ctx.agentRegistry.keys()).join(", ")}`, + ); + } + + // Build prompt from step configuration + const prompt = buildPromptForStep(planStep, inputData, ctx); + + // Execute via mock agent + const response = await agent.generate(prompt); + return response.object; + } + + case "tool": { + // Stub for future implementation + throw new Error( + `Tool executor not yet implemented. Step "${planStep.id}" uses tool "${executor.ref}".`, + ); + } + + case "workflow": { + // Stub for future implementation + throw new Error( + `Workflow executor not yet implemented. Step "${planStep.id}" uses workflow "${executor.ref}".`, + ); + } + + case "human": { + // Stub for future HITL implementation + throw new Error( + `Human executor not yet implemented. Step "${planStep.id}" requires human intervention. ` + + `Instructions: ${executor.instructions ?? "None provided"}`, + ); + } + + default: { + const exhaustiveCheck: never = executor; + throw new Error( + `Unknown executor kind: ${JSON.stringify(exhaustiveCheck)}`, + ); + } + } } // ============================================================================= @@ -320,18 +419,7 @@ export function compilePlanToWorkflow( /** * Creates a Mastra step from a PlanStep with streaming instrumentation. */ -function createMastraStep( - planStep: PlanStep, - ctx: CompilerContext, -): Step< - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny -> { +function createMastraStep(planStep: PlanStep, ctx: CompilerContext) { const depth = ctx.topology.depthMap.get(planStep.id) ?? 0; // Build input/output schemas from data contracts @@ -347,7 +435,7 @@ function createMastraStep( const startTime = Date.now(); // Emit step start event - await writer?.custom({ + await writer.custom({ type: "data-plan-step-start", data: { stepId: planStep.id, @@ -366,7 +454,7 @@ function createMastraStep( const durationMs = Date.now() - startTime; // Emit step complete event - await writer?.custom({ + await writer.custom({ type: "data-plan-step-complete", data: { stepId: planStep.id, @@ -385,7 +473,7 @@ function createMastraStep( const durationMs = Date.now() - startTime; // Emit step error event - await writer?.custom({ + await writer.custom({ type: "data-plan-step-error", data: { stepId: planStep.id, @@ -402,65 +490,6 @@ function createMastraStep( }); } -/** - * Executes a step based on its executor binding. - */ -async function executeStep( - planStep: PlanStep, - inputData: unknown, - ctx: CompilerContext, -): Promise { - const { executor } = planStep; - - switch (executor.kind) { - case "agent": { - const agent = ctx.agentRegistry.get(executor.ref); - if (!agent) { - throw new Error( - `Agent "${executor.ref}" not found in registry. ` + - `Available agents: ${Array.from(ctx.agentRegistry.keys()).join(", ")}`, - ); - } - - // Build prompt from step configuration - const prompt = buildPromptForStep(planStep, inputData, ctx); - - // Execute via mock agent - const response = await agent.generate(prompt); - return response.object; - } - - case "tool": { - // Stub for future implementation - throw new Error( - `Tool executor not yet implemented. Step "${planStep.id}" uses tool "${executor.ref}".`, - ); - } - - case "workflow": { - // Stub for future implementation - throw new Error( - `Workflow executor not yet implemented. Step "${planStep.id}" uses workflow "${executor.ref}".`, - ); - } - - case "human": { - // Stub for future HITL implementation - throw new Error( - `Human executor not yet implemented. Step "${planStep.id}" requires human intervention. ` + - `Instructions: ${executor.instructions ?? "None provided"}`, - ); - } - - default: { - const exhaustiveCheck: never = executor; - throw new Error( - `Unknown executor kind: ${JSON.stringify(exhaustiveCheck)}`, - ); - } - } -} - // ============================================================================= // WORKFLOW FLOW BUILDING // ============================================================================= @@ -475,15 +504,8 @@ async function executeStep( * - Wrap with entry/exit handlers for streaming events */ function buildWorkflowFromGroups( - workflow: Workflow< - typeof compiledWorkflowInputSchema, - typeof compiledWorkflowOutputSchema, - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny, - z.ZodTypeAny - >, + // eslint-disable-next-line @typescript-eslint/no-explicit-any + workflow: Workflow, ctx: CompilerContext, ): void { const { plan, topology } = ctx; @@ -500,7 +522,7 @@ function buildWorkflowFromGroups( workflow.map(async ({ inputData, writer }) => { executionState.startTime = Date.now(); - await writer?.custom({ + await writer.custom({ type: "data-plan-start", data: { planId: plan.id, @@ -512,6 +534,7 @@ function buildWorkflowFromGroups( }, } satisfies PlanStartEvent); + // eslint-disable-next-line @typescript-eslint/no-unsafe-return return inputData; }); @@ -521,20 +544,22 @@ function buildWorkflowFromGroups( for (const group of topology.parallelGroups) { const stepsInGroup = group.stepIds .map((id) => ctx.steps.get(id)) - .filter((s): s is NonNullable => s !== undefined); + .filter((step): step is NonNullable => step !== undefined); - if (stepsInGroup.length === 0) continue; + if (stepsInGroup.length === 0) { + continue; + } // Emit depth transition event if depth changed if (group.depth !== previousDepth && previousDepth >= 0) { const fromDepth = previousDepth; const toDepth = group.depth; const stepsCompletedAtDepth = - topology.parallelGroups.find((g) => g.depth === fromDepth)?.stepIds + topology.parallelGroups.find((grp) => grp.depth === fromDepth)?.stepIds .length ?? 0; workflow.map(async ({ inputData, writer }) => { - await writer?.custom({ + await writer.custom({ type: "data-plan-depth-transition", data: { fromDepth, @@ -544,6 +569,7 @@ function buildWorkflowFromGroups( }, } satisfies PlanDepthTransitionEvent); + // eslint-disable-next-line @typescript-eslint/no-unsafe-return return inputData; }); } @@ -558,7 +584,7 @@ function buildWorkflowFromGroups( // Multiple steps - check if all are parallelizable const parallelizableSteps = group.parallelizableStepIds .map((id) => ctx.steps.get(id)) - .filter((s): s is NonNullable => s !== undefined); + .filter((step): step is NonNullable => step !== undefined); if (parallelizableSteps.length === stepsInGroup.length) { // All parallelizable - use .parallel() @@ -567,7 +593,7 @@ function buildWorkflowFromGroups( // Mixed: parallel first, then sequential workflow.parallel(parallelizableSteps); const sequentialSteps = stepsInGroup.filter( - (s) => !parallelizableSteps.includes(s), + (step) => !parallelizableSteps.includes(step), ); for (const step of sequentialSteps) { workflow.then(step); @@ -583,11 +609,11 @@ function buildWorkflowFromGroups( // Emit progress after each group const currentDepth = group.depth; const completedAtThisPoint = topology.parallelGroups - .filter((g) => g.depth <= currentDepth) - .flatMap((g) => g.stepIds); + .filter((grp) => grp.depth <= currentDepth) + .flatMap((grp) => grp.stepIds); workflow.map(async ({ inputData, writer }) => { - await writer?.custom({ + await writer.custom({ type: "data-plan-progress", data: { completedSteps: completedAtThisPoint.length, @@ -597,6 +623,7 @@ function buildWorkflowFromGroups( }, } satisfies PlanProgressEvent); + // eslint-disable-next-line @typescript-eslint/no-unsafe-return return inputData; }); } @@ -605,7 +632,7 @@ function buildWorkflowFromGroups( workflow.map(async ({ inputData, writer }) => { const totalDurationMs = Date.now() - executionState.startTime; - await writer?.custom({ + await writer.custom({ type: "data-plan-complete", data: { planId: plan.id, @@ -629,139 +656,79 @@ function buildWorkflowFromGroups( } // ============================================================================= -// HELPER FUNCTIONS +// MAIN COMPILER FUNCTION // ============================================================================= /** - * Build input schema from step's data contracts. - */ -function buildInputSchema(planStep: PlanStep): z.ZodType { - if (planStep.inputs.length === 0) { - return z.object({}).passthrough(); - } - - const fields: Record> = {}; - for (const input of planStep.inputs) { - fields[input.name] = z.unknown().describe(input.description); - } - - return z.object(fields).passthrough(); -} - -/** - * Build output schema from step's data contracts. - */ -function buildOutputSchema(planStep: PlanStep): z.ZodType { - return z - .object({ - stepId: z.string(), - result: z.unknown(), - durationMs: z.number(), - }) - .passthrough(); -} - -/** - * Build a prompt for step execution based on step configuration. + * Compiles a validated PlanSpec into a Mastra Workflow. + * + * The compilation strategy: + * 1. Analyze topology to get parallel groups and execution order + * 2. Create Mastra steps for each PlanStep with streaming instrumentation + * 3. Build workflow using parallel groups: + * - Single step at a depth → .then() + * - Multiple parallelizable steps at same depth → .parallel() + * + * @param plan - A validated PlanSpec (call validatePlan first!) + * @param options - Compilation options + * @returns Compiled Mastra workflow ready for execution + * + * @example + * ```typescript + * const plan = await generatePlan({ goal: "..." }); + * const validation = validatePlan(plan); + * if (!validation.valid) throw new Error("Invalid plan"); + * + * const workflow = compilePlanToWorkflow(plan, { useMockAgents: true }); + * const run = workflow.createRun(); + * const result = await run.start({ context: {} }); + * ``` */ -function buildPromptForStep( - planStep: PlanStep, - inputData: unknown, - ctx: CompilerContext, -): string { - const parts: string[] = []; - - parts.push(`## Task: ${planStep.description}`); - parts.push(`Step ID: ${planStep.id}`); - parts.push(""); - - // Add step-type specific context - switch (planStep.type) { - case "research": - parts.push(`Research Query: ${planStep.query}`); - parts.push(`Stopping Rule: ${planStep.stoppingRule}`); - break; - - case "synthesize": - parts.push(`Mode: ${planStep.mode}`); - parts.push(`Input Step IDs: ${planStep.inputStepIds.join(", ")}`); - if (planStep.mode === "evaluative" && planStep.evaluateAgainst) { - parts.push(`Evaluate Against: ${planStep.evaluateAgainst.join(", ")}`); - } - break; - - case "experiment": - parts.push(`Mode: ${planStep.mode}`); - parts.push(`Procedure: ${planStep.procedure}`); - parts.push(`Success Criteria: ${planStep.successCriteria.join(", ")}`); - // Reference hypotheses - const hypotheses = planStep.hypothesisIds - .map((id) => ctx.plan.hypotheses.find((h) => h.id === id)) - .filter((h): h is NonNullable => h !== undefined); - if (hypotheses.length > 0) { - parts.push(`Hypotheses to Test:`); - for (const h of hypotheses) { - parts.push(` - ${h.id}: ${h.statement}`); - } - } - break; - - case "develop": - parts.push(`Specification: ${planStep.specification}`); - parts.push(`Deliverables: ${planStep.deliverables.join(", ")}`); - break; - } - - // Add input data context if present - if ( - inputData && - typeof inputData === "object" && - Object.keys(inputData).length > 0 - ) { - parts.push(""); - parts.push("## Input Data"); - parts.push("```json"); - parts.push(JSON.stringify(inputData, null, 2)); - parts.push("```"); - } +export function compilePlanToWorkflow( + plan: PlanSpec, + options: CompilerOptions = {}, +) { + // Normalize options + const normalizedOptions: Required = { + useMockAgents: options.useMockAgents ?? true, + mockDelayMs: options.mockDelayMs ?? 100, + agentRegistry: + options.agentRegistry ?? + createMockAgentRegistry({ simulatedDelayMs: options.mockDelayMs ?? 100 }), + }; - // Add evaluation criteria if present - if (planStep.evalCriteria) { - parts.push(""); - parts.push("## Success Criteria"); - parts.push(`Success: ${planStep.evalCriteria.successCondition}`); - if (planStep.evalCriteria.failureCondition) { - parts.push(`Failure: ${planStep.evalCriteria.failureCondition}`); - } - } + // Analyze topology + const topology = analyzePlanTopology(plan); - return parts.join("\n"); -} + // Build compiler context + const ctx: CompilerContext = { + plan, + topology, + options: normalizedOptions, + agentRegistry: normalizedOptions.agentRegistry, + steps: new Map(), + }; -/** - * Summarize output for streaming events. - */ -function summarizeOutput(result: unknown): string { - if (result === null || result === undefined) { - return ""; + // Phase 1: Create Mastra steps for each PlanStep + for (const planStep of plan.steps) { + const mastraStep = createMastraStep(planStep, ctx); + ctx.steps.set(planStep.id, mastraStep); } - if (typeof result === "string") { - return result.slice(0, 200) + (result.length > 200 ? "..." : ""); - } + // Phase 2: Create workflow + const workflow = createWorkflow({ + id: `compiled-plan-${plan.id}`, + inputSchema: compiledWorkflowInputSchema, + outputSchema: compiledWorkflowOutputSchema, + }); - if (typeof result === "object") { - // Check for mock response - if ("__mock" in result && result.__mock === true) { - const mock = result as MockResponse; - return `[Mock ${mock.stepType}] ${mock.stepId}`; - } + // Phase 3: Build workflow from parallel groups + buildWorkflowFromGroups(workflow, ctx); - const json = JSON.stringify(result); - return json.slice(0, 200) + (json.length > 200 ? "..." : ""); - } + // Phase 4: Commit and return + workflow.commit(); - return String(result).slice(0, 200); + return workflow; } // ============================================================================= From ed562d71f15caebab31e9fc728f7cc5a8b3fb79b Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Thu, 18 Dec 2025 16:30:20 +0100 Subject: [PATCH 03/16] tweak the clack-based demo --- apps/hash-ai-agent/package.json | 3 + .../decomposition-prompts/mock-plans.ts | 924 ++++++++++++++++++ .../src/mastra/scripts/demo-plan-execution.ts | 685 +++++++++++++ yarn.lock | 24 +- 4 files changed, 1625 insertions(+), 11 deletions(-) create mode 100644 apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts create mode 100644 apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts diff --git a/apps/hash-ai-agent/package.json b/apps/hash-ai-agent/package.json index 0f4f7fd8f40..d998a80684c 100644 --- a/apps/hash-ai-agent/package.json +++ b/apps/hash-ai-agent/package.json @@ -9,6 +9,7 @@ "scripts": { "build": "mastra build", "codegen": "tsx src/mastra/fixtures/generate-schemas.ts", + "demo:plan": "tsx src/mastra/scripts/demo-plan-execution.ts", "dev": "mastra dev", "eval": "RUN_LLM_SCORERS=true vitest run", "eval:dev": "RUN_LLM_SCORERS=true vitest dev", @@ -28,6 +29,7 @@ "@apidevtools/json-schema-ref-parser": "15.1.3", "@blockprotocol/graph": "0.4.0-canary.2", "@blockprotocol/type-system": "0.1.2-canary.1", + "@clack/prompts": "0.11.0", "@dmitryrechkin/json-schema-to-zod": "1.0.1", "@local/advanced-types": "0.0.0-private", "@local/hash-backend-utils": "0.0.0-private", @@ -46,6 +48,7 @@ "dedent": "1.7.0", "es-toolkit": "1.41.0", "json-schema": "0.4.0", + "picocolors": "1.1.1", "vitest": "4.0.15", "zod": "4.1.12", "zod-from-json-schema": "0.5.2" diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts new file mode 100644 index 00000000000..5e8867c186d --- /dev/null +++ b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts @@ -0,0 +1,924 @@ +/** + * Mock Plan Outputs — Cached PlanSpec for Each Fixture + * + * These are realistic PlanSpec outputs that match what the LLM would generate + * for each fixture. Used for: + * - Testing the TUI without burning API tokens + * - Running in CI + * - Faster iteration during development + * + * Run with: npx tsx src/mastra/scripts/demo-plan-execution.ts --mock + */ + +import type { PlanSpec } from "../../schemas/plan-spec"; + +// ============================================================================= +// SUMMARIZE PAPERS (Simplest) +// ============================================================================= + +/** + * Mock plan for summarize-papers fixture. + * Pattern: Parallel research → synthesize + */ +export const mockSummarizePapersPlan: PlanSpec = { + id: "summarize-papers-plan", + goalSummary: + "Summarize 3 recent papers on RAG and produce a comparison table", + aimType: "describe", + requirements: [ + { + id: "R1", + description: "Find and summarize 3 recent RAG papers (last 2 years)", + priority: "must", + }, + { + id: "R2", + description: + "Compare architecture, retrieval method, performance, limitations", + priority: "must", + }, + { + id: "R3", + description: "Produce a comparison table", + priority: "must", + }, + ], + hypotheses: [], + steps: [ + { + type: "research", + id: "S1", + description: "Search for recent RAG papers focusing on architecture", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [ + { name: "paper_1", description: "First RAG paper with summary" }, + ], + query: + "Recent retrieval-augmented generation architecture papers 2023-2024", + stoppingRule: + "Find 1 high-quality paper with clear architecture description", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "research", + id: "S2", + description: "Search for RAG papers focusing on retrieval methods", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [ + { name: "paper_2", description: "Second RAG paper with summary" }, + ], + query: "RAG retrieval methods dense sparse hybrid 2023-2024", + stoppingRule: "Find 1 high-quality paper with novel retrieval approach", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "research", + id: "S3", + description: "Search for RAG papers with performance benchmarks", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [ + { name: "paper_3", description: "Third RAG paper with summary" }, + ], + query: "RAG performance benchmarks evaluation 2023-2024", + stoppingRule: "Find 1 paper with comprehensive performance evaluation", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "synthesize", + id: "S4", + description: "Create comparison table from all three papers", + dependsOn: ["S1", "S2", "S3"], + requirementIds: ["R2", "R3"], + inputs: [ + { name: "paper_1", description: "First paper", fromStepId: "S1" }, + { name: "paper_2", description: "Second paper", fromStepId: "S2" }, + { name: "paper_3", description: "Third paper", fromStepId: "S3" }, + ], + outputs: [ + { + name: "comparison_table", + description: "Structured comparison of RAG approaches", + }, + ], + mode: "integrative", + inputStepIds: ["S1", "S2", "S3"], + parallelizable: false, + executor: { kind: "agent", ref: "result-synthesizer" }, + }, + ], + unknownsMap: { + knownKnowns: [ + "RAG combines retrieval with generation", + "Multiple architectural approaches exist", + ], + knownUnknowns: [ + "Which papers are most relevant to our use case", + "How to fairly compare different evaluation metrics", + ], + unknownUnknowns: [ + { + potentialSurprise: "All recent papers focus on same approach", + detectionSignal: + "Unable to find diverse architectures in search results", + }, + ], + communityCheck: + "Paper selection criteria and comparison dimensions should be transparent", + }, + estimatedComplexity: "low", +}; + +// ============================================================================= +// EXPLORE AND RECOMMEND (Parallel Research + Evaluative Synthesis) +// ============================================================================= + +/** + * Mock plan for explore-and-recommend fixture. + * Pattern: Parallel research on options → evaluative synthesis → recommendation + */ +export const mockExploreAndRecommendPlan: PlanSpec = { + id: "explore-and-recommend-plan", + goalSummary: + "Research vector database indexing approaches and recommend best for our use case", + aimType: "explain", + requirements: [ + { + id: "R1", + description: "Research HNSW indexing approach", + priority: "must", + }, + { + id: "R2", + description: "Research IVF indexing approach", + priority: "must", + }, + { + id: "R3", + description: "Research other promising approaches", + priority: "should", + }, + { + id: "R4", + description: + "Evaluate against: 10M docs, <100ms latency, similarity + filtering", + priority: "must", + }, + { + id: "R5", + description: "Provide justified recommendation", + priority: "must", + }, + ], + hypotheses: [], + steps: [ + { + type: "research", + id: "S1", + description: "Deep dive into HNSW indexing", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [ + { + name: "hnsw_analysis", + description: "HNSW characteristics, tradeoffs, benchmarks", + }, + ], + query: + "HNSW hierarchical navigable small world index performance characteristics filtered queries", + stoppingRule: + "Understand latency at scale, memory requirements, and filtering support", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "research", + id: "S2", + description: "Deep dive into IVF indexing", + dependsOn: [], + requirementIds: ["R2"], + inputs: [], + outputs: [ + { + name: "ivf_analysis", + description: "IVF characteristics, tradeoffs, benchmarks", + }, + ], + query: + "IVF inverted file index vector database performance nlist nprobe tradeoffs", + stoppingRule: + "Understand build time, query latency, and accuracy tradeoffs", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "research", + id: "S3", + description: "Research hybrid and emerging approaches", + dependsOn: [], + requirementIds: ["R3"], + inputs: [], + outputs: [ + { + name: "other_approaches", + description: "Analysis of DiskANN, ScaNN, and hybrid methods", + }, + ], + query: "DiskANN ScaNN hybrid vector index billion scale filtered search", + stoppingRule: "Identify 2-3 promising alternatives to HNSW and IVF", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "synthesize", + id: "S4", + description: "Compare all approaches against our requirements", + dependsOn: ["S1", "S2", "S3"], + requirementIds: ["R4"], + inputs: [ + { + name: "hnsw_analysis", + description: "HNSW research", + fromStepId: "S1", + }, + { name: "ivf_analysis", description: "IVF research", fromStepId: "S2" }, + { + name: "other_approaches", + description: "Other approaches", + fromStepId: "S3", + }, + ], + outputs: [ + { + name: "comparison_matrix", + description: + "Comparison against latency, memory, filtering requirements", + }, + ], + mode: "integrative", + inputStepIds: ["S1", "S2", "S3"], + parallelizable: false, + executor: { kind: "agent", ref: "result-synthesizer" }, + }, + { + type: "synthesize", + id: "S5", + description: "Evaluate options and make recommendation", + dependsOn: ["S4"], + requirementIds: ["R5"], + inputs: [ + { + name: "comparison_matrix", + description: "Comparison results", + fromStepId: "S4", + }, + ], + outputs: [ + { + name: "recommendation", + description: "Justified recommendation for our use case", + }, + ], + mode: "evaluative", + inputStepIds: ["S4"], + evaluateAgainst: [ + "Query latency <100ms at 10M scale", + "Memory efficiency for production deployment", + "Support for metadata filtering", + "Index build time within 3-week timeline", + ], + parallelizable: false, + executor: { kind: "agent", ref: "progress-evaluator" }, + }, + ], + unknownsMap: { + knownKnowns: [ + "HNSW is widely used for approximate nearest neighbor search", + "IVF offers controllable accuracy-speed tradeoff", + "Filtering adds complexity to vector search", + ], + knownUnknowns: [ + "How filtering performance scales with our data distribution", + "Whether hybrid approaches are production-ready", + "Actual memory requirements for our embedding dimensions", + ], + unknownUnknowns: [ + { + potentialSurprise: + "Our specific query patterns don't match benchmark assumptions", + detectionSignal: + "Large gap between published benchmarks and our prototype results", + }, + ], + communityCheck: + "Benchmark methodology and requirement prioritization should be reviewable", + }, + estimatedComplexity: "medium", +}; + +// ============================================================================= +// HYPOTHESIS VALIDATION (With Experiments) +// ============================================================================= + +/** + * Mock plan for hypothesis-validation fixture. + * Pattern: Research → hypothesis → experiment design → run → evaluate + */ +export const mockHypothesisValidationPlan: PlanSpec = { + id: "hypothesis-validation-plan", + goalSummary: + "Test whether fine-tuning outperforms few-shot prompting for entity extraction", + aimType: "predict", + requirements: [ + { + id: "R1", + description: "Establish baseline with few-shot GPT-4", + priority: "must", + }, + { + id: "R2", + description: "Fine-tune Llama 3 8B on labeled data", + priority: "must", + }, + { + id: "R3", + description: "Compare F1 scores rigorously", + priority: "must", + }, + { + id: "R4", + description: "Consider inference cost for production", + priority: "should", + }, + { + id: "R5", + description: "Justify recommendation to stakeholders", + priority: "must", + }, + ], + hypotheses: [ + { + id: "H1", + statement: + "Fine-tuned Llama 3 8B will achieve higher F1 than few-shot GPT-4 on legal entity extraction", + assumptions: [ + "5,000 labeled examples are sufficient for fine-tuning", + "Legal entity extraction benefits from domain-specific training", + "F1 score is an appropriate metric for this task", + ], + testableVia: + "Run both approaches on held-out test set and compare F1 scores", + status: "untested", + }, + { + id: "H2", + statement: + "Fine-tuned model will have significantly lower inference cost per document", + assumptions: [ + "Smaller model = lower cost", + "Fine-tuning doesn't require longer context", + ], + testableVia: "Measure tokens/latency per document for both approaches", + status: "untested", + }, + ], + steps: [ + { + type: "research", + id: "S1", + description: "Review prior work on fine-tuning vs few-shot for NER", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [ + { + name: "prior_work", + description: + "Summary of relevant papers and expected performance gaps", + }, + ], + query: + "Fine-tuning vs few-shot prompting named entity recognition legal documents comparison", + stoppingRule: "Find 3+ relevant comparisons with quantitative results", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "experiment", + id: "S2", + description: "Establish few-shot GPT-4 baseline", + dependsOn: ["S1"], + requirementIds: ["R1"], + inputs: [ + { + name: "prior_work", + description: "Inform prompt design", + fromStepId: "S1", + }, + ], + outputs: [ + { + name: "baseline_results", + description: "GPT-4 F1 scores on test set", + }, + ], + mode: "exploratory", + hypothesisIds: ["H1"], + procedure: + "Design 5-shot prompt with representative examples, run on 500 test documents, compute F1", + expectedOutcomes: [ + "F1 between 0.7-0.9 based on prior work", + "Identify challenging entity types", + ], + successCriteria: [ + "Complete evaluation on all test documents", + "F1 score computed for each entity type", + ], + parallelizable: true, + executor: { kind: "agent", ref: "experiment-runner" }, + }, + { + type: "develop", + id: "S3", + description: "Fine-tune Llama 3 8B on training data", + dependsOn: ["S1"], + requirementIds: ["R2"], + inputs: [ + { + name: "prior_work", + description: "Inform fine-tuning approach", + fromStepId: "S1", + }, + ], + outputs: [ + { + name: "fine_tuned_model", + description: "Fine-tuned Llama 3 8B checkpoint", + }, + ], + specification: + "Fine-tune Llama 3 8B using 4,500 training examples with LoRA, 500 for validation", + deliverables: [ + "Model checkpoint", + "Training curves", + "Validation F1 progression", + ], + parallelizable: true, + executor: { kind: "agent", ref: "code-writer" }, + }, + { + type: "experiment", + id: "S4", + description: "Evaluate fine-tuned model on test set", + dependsOn: ["S3"], + requirementIds: ["R3"], + inputs: [ + { + name: "fine_tuned_model", + description: "Trained model", + fromStepId: "S3", + }, + ], + outputs: [ + { + name: "finetuned_results", + description: "Fine-tuned model F1 scores on test set", + }, + ], + mode: "confirmatory", + hypothesisIds: ["H1", "H2"], + procedure: + "Run fine-tuned model on same 500 test documents, compute F1, measure inference time", + expectedOutcomes: [ + "If H1 true: F1 > baseline by >0.05", + "If H1 false: F1 within 0.05 of baseline", + ], + successCriteria: [ + "Complete evaluation on all test documents", + "Statistical significance computed", + ], + preregisteredCommitments: [ + "Use same test set as baseline", + "Report all entity types, not just best performing", + "Significance threshold: p < 0.05", + ], + parallelizable: false, + executor: { kind: "agent", ref: "experiment-runner" }, + }, + { + type: "synthesize", + id: "S5", + description: "Analyze results and make recommendation", + dependsOn: ["S2", "S4"], + requirementIds: ["R4", "R5"], + inputs: [ + { + name: "baseline_results", + description: "GPT-4 baseline", + fromStepId: "S2", + }, + { + name: "finetuned_results", + description: "Fine-tuned results", + fromStepId: "S4", + }, + ], + outputs: [ + { + name: "recommendation", + description: "Justified recommendation with supporting evidence", + }, + ], + mode: "evaluative", + inputStepIds: ["S2", "S4"], + evaluateAgainst: [ + "F1 score comparison (primary metric)", + "Inference cost at 10K docs/day", + "Stakeholder explainability", + ], + parallelizable: false, + executor: { kind: "agent", ref: "progress-evaluator" }, + }, + ], + unknownsMap: { + knownKnowns: [ + "We have 5,000 high-quality labeled examples", + "Legal NER includes: parties, dates, amounts, terms, obligations", + "GPT-4 has strong few-shot capabilities", + ], + knownUnknowns: [ + "Optimal number of fine-tuning epochs", + "Whether LoRA is sufficient or full fine-tuning needed", + "Distribution shift between training and production documents", + ], + unknownUnknowns: [ + { + potentialSurprise: + "Legal documents have formatting that confuses the tokenizer", + detectionSignal: + "High error rate on documents with tables or unusual formatting", + }, + { + potentialSurprise: "Entity types have different optimal approaches", + detectionSignal: + "Large variance in F1 across entity types for one approach", + }, + ], + communityCheck: + "Test set composition, prompt design, and fine-tuning hyperparameters should be documented", + }, + estimatedComplexity: "high", +}; + +// ============================================================================= +// CT DATABASE GOAL (Full R&D Cycle) +// ============================================================================= + +/** + * Mock plan for ct-database-goal fixture. + * Pattern: Multi-phase R&D with research, experimentation, and development + */ +export const mockCtDatabasePlan: PlanSpec = { + id: "ct-database-plan", + goalSummary: + "Create a category-theory native database with competitive query performance", + aimType: "intervene", + requirements: [ + { + id: "R1", + description: "Literature review of CT in databases and PLs", + priority: "must", + }, + { + id: "R2", + description: "Feasibility: represent and query CT structures", + priority: "must", + }, + { + id: "R3", + description: "Performance benchmarks vs traditional approaches", + priority: "must", + }, + { + id: "R4", + description: "Prototype if experiments promising", + priority: "should", + }, + { + id: "R5", + description: "Explore functors for schema migrations", + priority: "could", + }, + ], + hypotheses: [ + { + id: "H1", + statement: + "CT concepts (objects, morphisms) can be efficiently indexed for query", + assumptions: [ + "CT structures have regular patterns exploitable by indexes", + "Query patterns are known in advance", + ], + testableVia: "Implement basic indexing and measure query latency", + status: "untested", + }, + { + id: "H2", + statement: + "Functors can express schema migrations more naturally than ALTER TABLE", + assumptions: [ + "Schema changes follow categorical patterns", + "Users understand functor semantics", + ], + testableVia: + "Implement functor-based migrations and compare to SQL migrations", + status: "untested", + }, + { + id: "H3", + statement: + "Natural transformations can express data transformations type-safely", + assumptions: [ + "Data transformations preserve structure", + "Type system can encode naturality", + ], + testableVia: "Implement NT-based transforms and check type safety", + status: "untested", + }, + ], + steps: [ + { + type: "research", + id: "S1", + description: "Survey CT foundations in database theory", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [ + { + name: "db_theory_survey", + description: "Survey of categorical database theory", + }, + ], + query: + "Category theory database foundations functorial data migration categorical query language", + stoppingRule: "Identify key papers: Spivak, Schultz, CQL", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "research", + id: "S2", + description: "Survey CT in programming languages", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [ + { name: "pl_theory_survey", description: "Survey of CT in PLs" }, + ], + query: + "Category theory programming languages Haskell categorical semantics type theory", + stoppingRule: "Understand how Haskell/ML encode CT concepts", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "research", + id: "S3", + description: + "Analyze existing CT-based systems (CQL, Algebraic Databases)", + dependsOn: [], + requirementIds: ["R1"], + inputs: [], + outputs: [ + { + name: "existing_systems", + description: "Analysis of prior implementations", + }, + ], + query: + "CQL categorical query language implementation Algebraic Databases performance", + stoppingRule: + "Document architecture, limitations, and performance of 2+ systems", + parallelizable: true, + executor: { kind: "agent", ref: "literature-searcher" }, + }, + { + type: "synthesize", + id: "S4", + description: "Synthesize research into design principles", + dependsOn: ["S1", "S2", "S3"], + requirementIds: ["R1"], + inputs: [ + { + name: "db_theory_survey", + description: "DB theory", + fromStepId: "S1", + }, + { + name: "pl_theory_survey", + description: "PL theory", + fromStepId: "S2", + }, + { + name: "existing_systems", + description: "Existing systems", + fromStepId: "S3", + }, + ], + outputs: [ + { + name: "design_principles", + description: "Principles for CT-native database design", + }, + ], + mode: "integrative", + inputStepIds: ["S1", "S2", "S3"], + parallelizable: false, + executor: { kind: "agent", ref: "result-synthesizer" }, + }, + { + type: "experiment", + id: "S5", + description: "Feasibility: Implement and index basic CT structures", + dependsOn: ["S4"], + requirementIds: ["R2"], + inputs: [ + { + name: "design_principles", + description: "Design guidance", + fromStepId: "S4", + }, + ], + outputs: [ + { + name: "feasibility_results", + description: "Can CT structures be indexed efficiently?", + }, + ], + mode: "exploratory", + hypothesisIds: ["H1"], + procedure: + "Implement objects/morphisms in Rust, create B-tree indexes, measure query latency", + expectedOutcomes: [ + "Query latency within 10x of relational for simple queries", + "Identify indexing challenges", + ], + successCriteria: [ + "Complete implementation of basic structures", + "Benchmark results for 3 query types", + ], + parallelizable: false, + executor: { kind: "agent", ref: "experiment-runner" }, + }, + { + type: "experiment", + id: "S6", + description: "Performance: Benchmark against PostgreSQL", + dependsOn: ["S5"], + requirementIds: ["R3"], + inputs: [ + { + name: "feasibility_results", + description: "Feasibility results", + fromStepId: "S5", + }, + ], + outputs: [ + { name: "benchmark_results", description: "Performance comparison" }, + ], + mode: "confirmatory", + hypothesisIds: ["H1"], + procedure: + "Define 5 benchmark queries, run on equivalent PostgreSQL schema, compare latency", + expectedOutcomes: [ + "If promising: within 2x of PostgreSQL", + "If not: identify bottlenecks", + ], + successCriteria: [ + "All 5 queries benchmarked", + "Statistical confidence in results", + ], + preregisteredCommitments: [ + "Same data size for both systems", + "Warm cache for both", + "Report median and p99 latency", + ], + parallelizable: false, + executor: { kind: "agent", ref: "experiment-runner" }, + }, + { + type: "synthesize", + id: "S7", + description: "Go/no-go decision on prototype development", + dependsOn: ["S6"], + requirementIds: ["R4"], + inputs: [ + { + name: "benchmark_results", + description: "Benchmark results", + fromStepId: "S6", + }, + ], + outputs: [ + { name: "go_decision", description: "Decision and justification" }, + ], + mode: "evaluative", + inputStepIds: ["S6"], + evaluateAgainst: [ + "Performance within 2x of traditional DB", + "Clear path to optimization", + "Team has capacity for 6+ month project", + ], + parallelizable: false, + executor: { kind: "agent", ref: "progress-evaluator" }, + }, + { + type: "develop", + id: "S8", + description: "Develop prototype with functor-based migrations", + dependsOn: ["S7"], + requirementIds: ["R4", "R5"], + inputs: [ + { name: "go_decision", description: "Go decision", fromStepId: "S7" }, + ], + outputs: [ + { + name: "prototype", + description: "Working prototype with functor migrations", + }, + ], + specification: + "Build on feasibility code, add functor-based schema migrations, basic query language", + deliverables: [ + "Rust crate with CT primitives", + "Migration DSL", + "Query language parser", + "Documentation", + ], + parallelizable: false, + executor: { kind: "agent", ref: "code-writer" }, + }, + ], + unknownsMap: { + knownKnowns: [ + "Category theory has been applied to databases (Spivak et al.)", + "CQL exists as prior art", + "Rust is suitable for database implementation", + ], + knownUnknowns: [ + "Performance characteristics at scale", + "User experience of CT-based query language", + "Integration path with existing systems", + ], + unknownUnknowns: [ + { + potentialSurprise: "CT abstraction level too high for practical use", + detectionSignal: "Users struggle to express common queries", + }, + { + potentialSurprise: + "Impedance mismatch with traditional systems insurmountable", + detectionSignal: "Every integration requires complex translation layer", + }, + { + potentialSurprise: + "Theoretical elegance doesn't translate to performance", + detectionSignal: "Fundamental data structure limitations emerge", + }, + ], + communityCheck: + "Benchmark methodology, design decisions, and CT-to-performance tradeoffs should be documented for review", + }, + estimatedComplexity: "very-high", +}; + +// ============================================================================= +// EXPORTS +// ============================================================================= + +/** + * Map of fixture ID to mock plan for easy lookup. + */ +export const MOCK_PLANS: Record = { + "summarize-papers": mockSummarizePapersPlan, + "explore-and-recommend": mockExploreAndRecommendPlan, + "hypothesis-validation": mockHypothesisValidationPlan, + "ct-database-goal": mockCtDatabasePlan, +}; + +/** + * Get mock plan for a fixture ID. + */ +export function getMockPlan(fixtureId: string): PlanSpec | undefined { + return MOCK_PLANS[fixtureId]; +} diff --git a/apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts b/apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts new file mode 100644 index 00000000000..72aa7d3b449 --- /dev/null +++ b/apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts @@ -0,0 +1,685 @@ +#!/usr/bin/env tsx +/** + * Plan Execution TUI Demo + * + * A terminal UI for visualizing plan generation and execution. + * Uses @clack/prompts to display streaming events in real-time. + * + * Modes: + * - Real mode (default): Uses LLM to generate plans from fixture goals + * - Mock mode (--mock): Uses cached plans for fast iteration + * + * Usage: + * npx tsx src/mastra/scripts/demo-plan-execution.ts + * npx tsx src/mastra/scripts/demo-plan-execution.ts --mock + * npx tsx src/mastra/scripts/demo-plan-execution.ts --fixture=summarize-papers + * npx tsx src/mastra/scripts/demo-plan-execution.ts --mock --fixture=ct-database-goal + * npx tsx src/mastra/scripts/demo-plan-execution.ts --mock --fast # 100ms delay for testing + */ + +// eslint-disable-next-line id-length -- clack convention +import * as p from "@clack/prompts"; +import color from "picocolors"; + +import { + ctDatabaseGoalFixture, + exploreAndRecommendFixture, + hypothesisValidationFixture, + type PlanningFixture, + summarizePapersFixture, +} from "../fixtures/decomposition-prompts/fixtures"; +import { getMockPlan } from "../fixtures/decomposition-prompts/mock-plans"; +import type { + Executor, + PlanSpec, + PlanStep, + StepType, +} from "../schemas/plan-spec"; +import { + compilePlanToWorkflow, + type PlanExecutionEvent, +} from "../tools/plan-compiler"; +import { planningWorkflow } from "../workflows/planning-workflow"; + +// ============================================================================= +// FIXTURES +// ============================================================================= + +/** + * All available fixtures with display metadata. + */ +const FIXTURES: Array<{ + fixture: PlanningFixture; + label: string; + hint: string; +}> = [ + { + fixture: summarizePapersFixture, + label: "Summarize Papers", + hint: "Simplest — parallel research → synthesize (3-6 steps)", + }, + { + fixture: exploreAndRecommendFixture, + label: "Explore & Recommend", + hint: "Medium — parallel research → evaluative synthesis (4-8 steps)", + }, + { + fixture: hypothesisValidationFixture, + label: "Hypothesis Validation", + hint: "Complex — research → experiment → synthesize (5-10 steps)", + }, + { + fixture: ctDatabaseGoalFixture, + label: "CT Database Goal", + hint: "Full R&D cycle — all step types (8-15+ steps)", + }, +]; + +// ============================================================================= +// CLI ARGUMENT PARSING +// ============================================================================= + +interface CliArgs { + mock: boolean; + fast: boolean; + fixture?: string; + delay?: number; +} + +function parseCliArgs(): CliArgs { + const args = process.argv.slice(2); + const result: CliArgs = { + mock: false, + fast: false, + }; + + for (const arg of args) { + if (arg === "--mock") { + result.mock = true; + } else if (arg === "--fast") { + result.fast = true; + } else if (arg.startsWith("--fixture=")) { + result.fixture = arg.split("=")[1]; + } else if (arg.startsWith("--delay=")) { + result.delay = parseInt(arg.split("=")[1]!, 10); + } + } + + return result; +} + +// ============================================================================= +// HELPERS +// ============================================================================= + +function delay(ms: number): Promise { + return new Promise((resolve) => { + setTimeout(resolve, ms); + }); +} + +// ============================================================================= +// UI HELPERS +// ============================================================================= + +const STEP_TYPE_ICONS: Record = { + research: "🔍", + synthesize: "🔗", + experiment: "🧪", + develop: "🛠️", +}; + +const STEP_TYPE_COLORS: Record string> = { + research: color.blue, + synthesize: color.magenta, + experiment: color.yellow, + develop: color.green, +}; + +function formatStepType(stepType: StepType): string { + const icon = STEP_TYPE_ICONS[stepType]; + const colorFn = STEP_TYPE_COLORS[stepType]; + return `${icon} ${colorFn(stepType)}`; +} + +function formatDuration(ms: number): string { + if (ms < 1000) { + return `${ms}ms`; + } + return `${(ms / 1000).toFixed(2)}s`; +} + +function getExecutorRef(executor: Executor): string { + if (executor.kind === "human") { + return "human"; + } + return executor.ref; +} + +/** + * Write a line to stdout without extra spacing. + * Clack's p.log.message() adds blank lines between messages, + * which is too verbose for streaming output. + */ +function writeLine(line: string): void { + process.stdout.write(`${color.gray("│")} ${line}\n`); +} + +/** + * Format a step for display in the plan visualization. + */ +function formatStepForDisplay(step: PlanStep, depth: number): string[] { + const lines: string[] = []; + const indent = " ".repeat(depth); + const icon = STEP_TYPE_ICONS[step.type]; + const colorFn = STEP_TYPE_COLORS[step.type]; + + // Main step line + lines.push(`${indent}${icon} ${colorFn(step.id)} — ${step.description}`); + + // Dependencies + if (step.dependsOn.length > 0) { + lines.push( + `${indent} ${color.dim(`depends on: ${step.dependsOn.join(", ")}`)}`, + ); + } + + // Executor + lines.push( + `${indent} ${color.dim(`executor: ${getExecutorRef(step.executor)}`)}`, + ); + + return lines; +} + +/** + * Display a nicely formatted visualization of the generated plan. + * Uses direct stdout writes to avoid extra blank lines from p.log.message(). + */ +function displayPlanVisualization(plan: PlanSpec): void { + p.log.step("Generated Plan Structure:"); + + // Goal summary + writeLine(`${color.bold("Goal:")} ${plan.goalSummary}`); + + // Requirements + if (plan.requirements.length > 0) { + writeLine(""); + writeLine(color.bold("Requirements:")); + for (const req of plan.requirements) { + const priorityColor = + req.priority === "must" + ? color.red + : req.priority === "should" + ? color.yellow + : color.dim; + writeLine( + ` ${priorityColor(`[${req.priority}]`)} ${req.id}: ${req.description}`, + ); + } + } + + // Hypotheses + if (plan.hypotheses.length > 0) { + writeLine(""); + writeLine(color.bold("Hypotheses:")); + for (const hyp of plan.hypotheses) { + writeLine(` ${color.cyan(hyp.id)}: ${hyp.statement}`); + writeLine(` ${color.dim(`testable via: ${hyp.testableVia}`)}`); + } + } + + // Steps organized by depth + writeLine(""); + writeLine(color.bold("Execution Steps:")); + + // Group steps by their dependencies to show structure + const entrySteps = plan.steps.filter((step) => step.dependsOn.length === 0); + const otherSteps = plan.steps.filter((step) => step.dependsOn.length > 0); + + // Show entry points (depth 0) + if (entrySteps.length > 0) { + writeLine(color.dim(" ┌─ Entry points (parallel):")); + for (const step of entrySteps) { + for (const line of formatStepForDisplay(step, 1)) { + writeLine(line); + } + } + } + + // Show dependent steps + if (otherSteps.length > 0) { + writeLine(color.dim(" │")); + writeLine(color.dim(" └─ Dependent steps:")); + for (const step of otherSteps) { + for (const line of formatStepForDisplay(step, 1)) { + writeLine(line); + } + } + } + + // Unknowns map summary + writeLine(""); + writeLine(color.bold("Unknowns Map:")); + writeLine( + ` ${color.green("Known knowns:")} ${plan.unknownsMap.knownKnowns.length} items`, + ); + writeLine( + ` ${color.yellow("Known unknowns:")} ${plan.unknownsMap.knownUnknowns.length} items`, + ); + writeLine( + ` ${color.red("Unknown unknowns:")} ${plan.unknownsMap.unknownUnknowns.length} items`, + ); +} + +// ============================================================================= +// PLAN GENERATION +// ============================================================================= + +/** + * Generate a plan from a fixture goal. + * In mock mode, returns the cached plan. Otherwise, uses the LLM. + */ +async function generatePlanFromFixture( + fixture: PlanningFixture, + useMock: boolean, + spinner: ReturnType, +): Promise<{ plan: PlanSpec; fromCache: boolean }> { + const fixtureId = fixture.input.id; + + if (useMock) { + spinner.message(`Loading cached plan for ${fixtureId}...`); + await delay(300); // Brief delay for visual feedback + + const mockPlan = getMockPlan(fixtureId); + if (!mockPlan) { + throw new Error(`No mock plan found for fixture: ${fixtureId}`); + } + return { plan: mockPlan, fromCache: true }; + } + + // Real LLM generation + spinner.message(`Generating plan from goal (this may take 30-60s)...`); + + const run = await planningWorkflow.createRun(); + const result = await run.start({ + inputData: { + goal: fixture.input.goal, + context: fixture.input.context, + maxAttempts: 3, + }, + }); + + if (result.status !== "success") { + throw new Error(`Planning workflow failed: ${result.status}`); + } + + // The result includes the output with plan, valid, attempts + const output = result.result as { + plan: PlanSpec; + valid: boolean; + attempts: number; + }; + + if (!output.valid) { + p.log.warn( + `Plan generated but validation failed after ${output.attempts} attempts`, + ); + } + + return { plan: output.plan, fromCache: false }; +} + +// ============================================================================= +// PLAN EXECUTION +// ============================================================================= +/** + * Execute a plan and stream progress to the TUI. + * + * NOTE: We intentionally avoid using spinners during streaming because + * spinners use cursor positioning (ANSI escape codes) that can interfere + * with log output, causing display corruption. Instead, we use plain + * stdout writes which are append-only and don't move the cursor. + */ +async function executePlan( + plan: PlanSpec, + delayMs: number, +): Promise<{ success: boolean; completedSteps: number; errorCount: number }> { + // Track state for UI updates + const stepStates = new Map< + string, + { status: "pending" | "running" | "done" | "error"; startTime?: number } + >(); + for (const step of plan.steps) { + stepStates.set(step.id, { status: "pending" }); + } + + let completedSteps = 0; + let errorCount = 0; + + // Compile the plan with mock agents + const workflow = compilePlanToWorkflow(plan, { + useMockAgents: true, + mockDelayMs: delayMs, + }); + + // Create workflow run and stream + const run = await workflow.createRun(); + const stream = run.stream({ inputData: { context: {} } }); + + // Process streaming events using direct stdout writes (no spinner, no extra spacing) + for await (const chunk of stream.fullStream) { + if (!chunk.type.startsWith("data-plan-")) { + continue; + } + + const event = chunk as unknown as PlanExecutionEvent; + + switch (event.type) { + case "data-plan-start": { + writeLine( + `${color.dim("┌")} Plan started: ${color.cyan(event.data.planId)}`, + ); + writeLine( + `${color.dim("│")} Steps: ${event.data.totalSteps}, Critical path: ${event.data.criticalPathLength}, Parallel groups: ${event.data.parallelGroups}`, + ); + break; + } + + case "data-plan-step-start": { + const { stepId, stepType, description, depth } = event.data; + stepStates.set(stepId, { status: "running", startTime: Date.now() }); + + const stepInfo = plan.steps.find((step) => step.id === stepId); + const depthIndicator = color.dim(`d${depth}`); + + writeLine( + `${color.dim("│")} ${color.yellow("▶")} ${formatStepType(stepType)} ${color.bold(stepId)} ${depthIndicator} — ${color.dim(description)}`, + ); + + if (stepInfo?.executor) { + writeLine( + `${color.dim("│")} executor: ${color.cyan(getExecutorRef(stepInfo.executor))}`, + ); + } + break; + } + + case "data-plan-step-complete": { + const { stepId, stepType, durationMs } = event.data; + stepStates.set(stepId, { status: "done" }); + completedSteps++; + + writeLine( + `${color.dim("│")} ${color.green("✓")} ${formatStepType(stepType)} ${color.bold(stepId)} ${color.dim(`(${formatDuration(durationMs)})`)} ${color.dim(`[${completedSteps}/${plan.steps.length}]`)}`, + ); + break; + } + + case "data-plan-step-error": { + const { stepId, stepType, error, durationMs } = event.data; + stepStates.set(stepId, { status: "error" }); + errorCount++; + + writeLine( + `${color.dim("│")} ${color.red("✗")} ${formatStepType(stepType)} ${color.bold(stepId)} ${color.dim(`(${formatDuration(durationMs)})`)}`, + ); + writeLine(`${color.dim("│")} ${color.red(error)}`); + break; + } + + case "data-plan-depth-transition": { + const { + fromDepth, + toDepth, + stepsCompletedAtDepth, + stepsStartingAtDepth, + } = event.data; + + writeLine( + `${color.dim("├──")} Depth ${fromDepth} → ${toDepth} ${color.dim(`(${stepsCompletedAtDepth} done, ${stepsStartingAtDepth} starting)`)}`, + ); + break; + } + + case "data-plan-progress": { + // Progress is shown inline with step completion + break; + } + + case "data-plan-complete": { + const { + planId, + success, + totalDurationMs, + stepsCompleted, + stepsFailed, + } = event.data; + + writeLine( + `${color.dim("└")} ${success ? color.green("Done") : color.red("Failed")}: ${planId} — ${color.cyan(formatDuration(totalDurationMs))}, ${stepsCompleted} completed, ${stepsFailed} failed`, + ); + break; + } + } + } + + return { + success: errorCount === 0, + completedSteps, + errorCount, + }; +} + +// ============================================================================= +// MAIN LOOP +// ============================================================================= + +/** + * Run a single demo iteration. + * Returns true to continue looping, false to exit. + */ +async function runDemoIteration(cliArgs: CliArgs): Promise { + // Fixture selection - use CLI arg or prompt + let selectedFixture: PlanningFixture; + + if (cliArgs.fixture) { + const found = FIXTURES.find( + (item) => item.fixture.input.id === cliArgs.fixture, + ); + if (!found) { + p.log.error(`Unknown fixture: ${cliArgs.fixture}`); + p.log.info( + `Available: ${FIXTURES.map((item) => item.fixture.input.id).join(", ")}`, + ); + return false; + } + selectedFixture = found.fixture; + p.log.info(`Fixture: ${color.cyan(found.label)} (from CLI)`); + } else { + const fixtureChoice = await p.select({ + message: "Select a fixture:", + options: [ + ...FIXTURES.map((item) => ({ + value: item.fixture.input.id, + label: item.label, + hint: item.hint, + })), + { value: "__exit__", label: "Exit", hint: "Quit the demo" }, + ], + }); + + if (p.isCancel(fixtureChoice) || fixtureChoice === "__exit__") { + return false; + } + + selectedFixture = FIXTURES.find( + (item) => item.fixture.input.id === fixtureChoice, + )!.fixture; + } + + // Delay selection - use CLI arg, --fast flag, or prompt + let delayMs: number; + + if (cliArgs.fast) { + delayMs = 100; + p.log.info(`Mock agent delay: ${color.cyan("100ms")} (--fast mode)`); + } else if (cliArgs.delay !== undefined) { + delayMs = cliArgs.delay; + p.log.info(`Mock agent delay: ${color.cyan(String(delayMs))}ms (from CLI)`); + } else { + const delayChoice = await p.select({ + message: "Select mock agent delay:", + options: [ + { value: 1000, label: "Normal (1s)", hint: "Comfortable pace" }, + { value: 2000, label: "Slow (2s)", hint: "Easy to follow" }, + { value: 3000, label: "Very slow (3s)", hint: "Step by step" }, + ], + }); + + if (p.isCancel(delayChoice)) { + return false; + } + + delayMs = delayChoice as number; + } + + // Display goal + p.log.step("Goal:"); + p.log.message(color.dim(selectedFixture.input.goal.trim())); + + if (selectedFixture.input.context) { + p.log.step("Context:"); + p.log.message(color.dim(selectedFixture.input.context.trim())); + } + + // Phase 1: Generate plan + p.log.step("Phase 1: Plan Generation"); + + const genSpinner = p.spinner(); + genSpinner.start( + cliArgs.mock ? "Loading cached plan..." : "Generating plan...", + ); + + let plan: PlanSpec; + let fromCache: boolean; + try { + const result = await generatePlanFromFixture( + selectedFixture, + cliArgs.mock, + genSpinner, + ); + plan = result.plan; + fromCache = result.fromCache; + genSpinner.stop( + `Plan ${fromCache ? "loaded" : "generated"}: ${color.cyan(plan.id)} (${plan.steps.length} steps)`, + ); + } catch (error) { + // spinner.stop(msg, code) - code 2 is error + genSpinner.stop( + `Plan generation failed: ${error instanceof Error ? error.message : String(error)}`, + 2, + ); + return !cliArgs.fixture; // Continue loop if interactive, exit if CLI-specified fixture + } + + // Show plan visualization (especially important for non-mock mode) + if (!fromCache) { + displayPlanVisualization(plan); + } else { + // Brief summary for cached plans + p.log.info(`Goal summary: ${color.cyan(plan.goalSummary)}`); + p.log.info( + `Steps: ${color.yellow(String(plan.steps.length))}, ` + + `Requirements: ${plan.requirements.length}, ` + + `Hypotheses: ${plan.hypotheses.length}`, + ); + } + + // Brief pause before execution + await delay(500); + + // Phase 2: Execute plan + p.log.step("Phase 2: Plan Execution"); + + const { success, completedSteps, errorCount } = await executePlan( + plan, + delayMs, + ); + + // Summary + p.log.message(""); + if (success) { + p.log.success(`All ${completedSteps} steps completed successfully!`); + } else { + p.log.error( + `Completed with errors: ${completedSteps} done, ${errorCount} failed`, + ); + } + + // If fixture was specified via CLI, don't loop + if (cliArgs.fixture) { + return false; + } + + // Wait for user to acknowledge before continuing + // This ensures they can read/scroll the output + p.log.message(""); + p.log.message(color.dim("─".repeat(50))); + + const runAnother = await p.confirm({ + message: "Run another demo?", + initialValue: false, + }); + + if (p.isCancel(runAnother) || !runAnother) { + return false; + } + + // Add visual separator before next run + p.log.message(""); + p.log.message(color.bgCyan(color.black(" Next Demo "))); + p.log.message(""); + + return true; // Continue looping +} + +// ============================================================================= +// MAIN +// ============================================================================= + +async function main() { + const cliArgs = parseCliArgs(); + + console.clear(); + + const modeLabel = cliArgs.mock + ? color.yellow(" MOCK MODE ") + : color.green(" REAL MODE "); + p.intro(`${color.bgCyan(color.black(" Plan Execution Demo "))} ${modeLabel}`); + + if (cliArgs.mock) { + p.log.info( + color.dim( + "Using cached plans for fast iteration. Remove --mock for real LLM calls.", + ), + ); + } + + if (cliArgs.fast) { + p.log.info(color.dim("Fast mode enabled (100ms delays).")); + } + + // Main loop - the runDemoIteration function handles continue/exit logic + let continueLoop = true; + while (continueLoop) { + continueLoop = await runDemoIteration(cliArgs); + } + + p.outro(color.dim("Thanks for using the Plan Execution Demo!")); +} + +main().catch((err) => { + p.log.error(String(err)); + process.exit(1); +}); diff --git a/yarn.lock b/yarn.lock index a8c15ccecef..1d7e715e6c1 100644 --- a/yarn.lock +++ b/yarn.lock @@ -581,6 +581,7 @@ __metadata: "@apidevtools/json-schema-ref-parser": "npm:15.1.3" "@blockprotocol/graph": "npm:0.4.0-canary.2" "@blockprotocol/type-system": "npm:0.1.2-canary.1" + "@clack/prompts": "npm:0.11.0" "@dmitryrechkin/json-schema-to-zod": "npm:1.0.1" "@local/advanced-types": "npm:0.0.0-private" "@local/eslint": "npm:0.0.0-private" @@ -616,6 +617,7 @@ __metadata: json-schema: "npm:0.4.0" mastra: "npm:1.0.0-beta.5" npm-run-all2: "npm:8.0.4" + picocolors: "npm:1.1.1" sanitize-html: "npm:2.17.0" tsx: "npm:4.20.6" typescript: "npm:5.9.3" @@ -6133,25 +6135,25 @@ __metadata: languageName: node linkType: hard -"@clack/prompts@npm:0.9.1": - version: 0.9.1 - resolution: "@clack/prompts@npm:0.9.1" +"@clack/prompts@npm:0.11.0, @clack/prompts@npm:^0.11.0": + version: 0.11.0 + resolution: "@clack/prompts@npm:0.11.0" dependencies: - "@clack/core": "npm:0.4.1" + "@clack/core": "npm:0.5.0" picocolors: "npm:^1.0.0" sisteransi: "npm:^1.0.5" - checksum: 10c0/6cda9f56963dcbbfca4d9a64c82cf57e7f00dd563cd9e9ad28973b10ac761723fc21453254effbf08d5862efd57bad41d48008316c345202b74035ae905329cf + checksum: 10c0/4c573f2adec3b9109fe861e36312be8ae7cc6e80a5128aa784b9aeafeda5001b23f66c08eca50f4491119b435d9587ec9862956be8c5be472ec3373275003ba8 languageName: node linkType: hard -"@clack/prompts@npm:^0.11.0": - version: 0.11.0 - resolution: "@clack/prompts@npm:0.11.0" +"@clack/prompts@npm:0.9.1": + version: 0.9.1 + resolution: "@clack/prompts@npm:0.9.1" dependencies: - "@clack/core": "npm:0.5.0" + "@clack/core": "npm:0.4.1" picocolors: "npm:^1.0.0" sisteransi: "npm:^1.0.5" - checksum: 10c0/4c573f2adec3b9109fe861e36312be8ae7cc6e80a5128aa784b9aeafeda5001b23f66c08eca50f4491119b435d9587ec9862956be8c5be472ec3373275003ba8 + checksum: 10c0/6cda9f56963dcbbfca4d9a64c82cf57e7f00dd563cd9e9ad28973b10ac761723fc21453254effbf08d5862efd57bad41d48008316c345202b74035ae905329cf languageName: node linkType: hard @@ -39643,7 +39645,7 @@ __metadata: languageName: node linkType: hard -"picocolors@npm:^1.0.0, picocolors@npm:^1.1.1": +"picocolors@npm:1.1.1, picocolors@npm:^1.0.0, picocolors@npm:^1.1.1": version: 1.1.1 resolution: "picocolors@npm:1.1.1" checksum: 10c0/e2e3e8170ab9d7c7421969adaa7e1b31434f789afb9b3f115f6b96d91945041ac3ceb02e9ec6fe6510ff036bcc0bf91e69a1772edc0b707e12b19c0f2d6bcf58 From b6be39bae8de5cf83c722e234d9a7394b4d1e74f Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Fri, 19 Dec 2025 12:00:02 +0100 Subject: [PATCH 04/16] minor AGENTS.md tweak --- AGENTS.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f94bc34e374..96e48e9363a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -82,17 +82,12 @@ For Rust packages, you can add features as needed with `--all-features`, specifi ## Contextual Rules -CRITICAL: For the files referenced below (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis, ONLY when relevant to the SPECIFIC task at hand. +CRITICAL: For the files referenced below, use your Read tool to load it on a need-to-know basis, ONLY when relevant to the SPECIFIC task at hand: + +- @.config/agents/rules/*.md Instructions: - Do NOT preemptively load all references - use lazy loading based on actual need - When loaded, treat content as mandatory instructions that override defaults - Follow references recursively when needed - -Rule files: - -- @.config/agents/rules/ark-ui.md -- @.config/agents/rules/mastra.md -- @.config/agents/rules/panda-css.md -- @.config/agents/rules/zod.md From fc9f1ab9d218a2c1b0569ab84b7d9d7980e123bf Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Fri, 19 Dec 2025 14:50:54 +0100 Subject: [PATCH 05/16] move /agent to /_ai --- apps/hash-ai-agent/{agent => _ai}/plans/CONDITIONAL-BRANCHING.md | 0 .../{agent => _ai}/plans/E2E-test-results-2024-12-17.md | 0 .../hash-ai-agent/{agent => _ai}/plans/PLAN-task-decomposition.md | 0 .../{agent => _ai}/plans/PR-task-decomposition-framework.md | 0 apps/hash-ai-agent/{agent => _ai}/plans/PROMPTS-meta-cognitive.md | 0 apps/hash-ai-agent/{agent => _ai}/plans/compiler-phase-1-done.md | 0 apps/hash-ai-agent/{agent => _ai}/wiki/harness-patterns.md | 0 apps/hash-ai-agent/{agent => _ai}/wiki/mastra-patterns.md | 0 8 files changed, 0 insertions(+), 0 deletions(-) rename apps/hash-ai-agent/{agent => _ai}/plans/CONDITIONAL-BRANCHING.md (100%) rename apps/hash-ai-agent/{agent => _ai}/plans/E2E-test-results-2024-12-17.md (100%) rename apps/hash-ai-agent/{agent => _ai}/plans/PLAN-task-decomposition.md (100%) rename apps/hash-ai-agent/{agent => _ai}/plans/PR-task-decomposition-framework.md (100%) rename apps/hash-ai-agent/{agent => _ai}/plans/PROMPTS-meta-cognitive.md (100%) rename apps/hash-ai-agent/{agent => _ai}/plans/compiler-phase-1-done.md (100%) rename apps/hash-ai-agent/{agent => _ai}/wiki/harness-patterns.md (100%) rename apps/hash-ai-agent/{agent => _ai}/wiki/mastra-patterns.md (100%) diff --git a/apps/hash-ai-agent/agent/plans/CONDITIONAL-BRANCHING.md b/apps/hash-ai-agent/_ai/plans/CONDITIONAL-BRANCHING.md similarity index 100% rename from apps/hash-ai-agent/agent/plans/CONDITIONAL-BRANCHING.md rename to apps/hash-ai-agent/_ai/plans/CONDITIONAL-BRANCHING.md diff --git a/apps/hash-ai-agent/agent/plans/E2E-test-results-2024-12-17.md b/apps/hash-ai-agent/_ai/plans/E2E-test-results-2024-12-17.md similarity index 100% rename from apps/hash-ai-agent/agent/plans/E2E-test-results-2024-12-17.md rename to apps/hash-ai-agent/_ai/plans/E2E-test-results-2024-12-17.md diff --git a/apps/hash-ai-agent/agent/plans/PLAN-task-decomposition.md b/apps/hash-ai-agent/_ai/plans/PLAN-task-decomposition.md similarity index 100% rename from apps/hash-ai-agent/agent/plans/PLAN-task-decomposition.md rename to apps/hash-ai-agent/_ai/plans/PLAN-task-decomposition.md diff --git a/apps/hash-ai-agent/agent/plans/PR-task-decomposition-framework.md b/apps/hash-ai-agent/_ai/plans/PR-task-decomposition-framework.md similarity index 100% rename from apps/hash-ai-agent/agent/plans/PR-task-decomposition-framework.md rename to apps/hash-ai-agent/_ai/plans/PR-task-decomposition-framework.md diff --git a/apps/hash-ai-agent/agent/plans/PROMPTS-meta-cognitive.md b/apps/hash-ai-agent/_ai/plans/PROMPTS-meta-cognitive.md similarity index 100% rename from apps/hash-ai-agent/agent/plans/PROMPTS-meta-cognitive.md rename to apps/hash-ai-agent/_ai/plans/PROMPTS-meta-cognitive.md diff --git a/apps/hash-ai-agent/agent/plans/compiler-phase-1-done.md b/apps/hash-ai-agent/_ai/plans/compiler-phase-1-done.md similarity index 100% rename from apps/hash-ai-agent/agent/plans/compiler-phase-1-done.md rename to apps/hash-ai-agent/_ai/plans/compiler-phase-1-done.md diff --git a/apps/hash-ai-agent/agent/wiki/harness-patterns.md b/apps/hash-ai-agent/_ai/wiki/harness-patterns.md similarity index 100% rename from apps/hash-ai-agent/agent/wiki/harness-patterns.md rename to apps/hash-ai-agent/_ai/wiki/harness-patterns.md diff --git a/apps/hash-ai-agent/agent/wiki/mastra-patterns.md b/apps/hash-ai-agent/_ai/wiki/mastra-patterns.md similarity index 100% rename from apps/hash-ai-agent/agent/wiki/mastra-patterns.md rename to apps/hash-ai-agent/_ai/wiki/mastra-patterns.md From 42709b8fff15d3874cd95e700a92d74be5679751 Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Fri, 19 Dec 2025 15:10:11 +0100 Subject: [PATCH 06/16] review, and synth/prune existing plans in to wiki --- .../_ai/plans/E2E-test-results-2024-12-17.md | 242 ---- .../_ai/plans/PLAN-task-decomposition.md | 1066 ----------------- .../plans/PR-task-decomposition-framework.md | 144 --- .../_ai/plans/compiler-phase-1-done.md | 39 - .../conditional-branching.md} | 5 +- .../hash-ai-agent/_ai/wiki/execution-state.md | 415 +++++++ .../_ai/wiki/gaps-and-next-steps.md | 229 ++++ .../hash-ai-agent/_ai/wiki/handoff-packets.md | 122 ++ .../meta-cognitive-prompts.md} | 0 9 files changed, 769 insertions(+), 1493 deletions(-) delete mode 100644 apps/hash-ai-agent/_ai/plans/E2E-test-results-2024-12-17.md delete mode 100644 apps/hash-ai-agent/_ai/plans/PLAN-task-decomposition.md delete mode 100644 apps/hash-ai-agent/_ai/plans/PR-task-decomposition-framework.md delete mode 100644 apps/hash-ai-agent/_ai/plans/compiler-phase-1-done.md rename apps/hash-ai-agent/_ai/{plans/CONDITIONAL-BRANCHING.md => wiki/conditional-branching.md} (97%) create mode 100644 apps/hash-ai-agent/_ai/wiki/execution-state.md create mode 100644 apps/hash-ai-agent/_ai/wiki/gaps-and-next-steps.md create mode 100644 apps/hash-ai-agent/_ai/wiki/handoff-packets.md rename apps/hash-ai-agent/_ai/{plans/PROMPTS-meta-cognitive.md => wiki/meta-cognitive-prompts.md} (100%) diff --git a/apps/hash-ai-agent/_ai/plans/E2E-test-results-2024-12-17.md b/apps/hash-ai-agent/_ai/plans/E2E-test-results-2024-12-17.md deleted file mode 100644 index c47a24ace91..00000000000 --- a/apps/hash-ai-agent/_ai/plans/E2E-test-results-2024-12-17.md +++ /dev/null @@ -1,242 +0,0 @@ -# E2E Test Results — Planning Pipeline - -**Date**: 2024-12-17 -**Test File**: `src/mastra/workflows/planning-workflow.test.ts` -**Duration**: ~98 seconds total - -## Overview - -These are the console outputs from running the E2E planning pipeline tests against all 4 fixtures. The tests generate plans using the planner agent, validate them, analyze topology, and run deterministic scorers. - -**Results**: 3/4 fixtures pass, 1 fails (known issue with preregistered commitments) - ---- - -## Individual Fixture Tests - -
-summarize-papers (4.2s) — PASS - -``` -============================================================ - FIXTURE: summarize-papers -============================================================ -Goal: Summarize 3 recent papers on retrieval-augmented generation (RAG) - and produce a comparis... - ---- Generating Plan --- - ID: rag-paper-summary-comparison-plan - Goal Summary: Summarize 3 recent RAG papers and create a comparison table.... - Steps: 3 - Requirements: 3 - Hypotheses: 0 - Step types: {"research":2,"synthesize":1} - ---- Validation --- - Valid: true - Errors: 0 - ---- Topology Analysis --- - Entry points: [S1] - Exit points: [S3] - Critical path: 3 steps - Parallel groups: 3 - ---- Deterministic Scores --- - Overall: 92.8% - Structure: 76.7% - Coverage: 100.0% - Experiment Rigor: 100.0% - Unknowns Coverage: 93.3% - ---- Expected Characteristics Check --- - All expected characteristics met - - (LLM scorers skipped — set RUN_LLM_SCORERS=true to enable) - - Duration: 4.2s -``` - -
- -
-explore-and-recommend (13.9s) — PASS (with notes) - -``` -============================================================ - FIXTURE: explore-and-recommend -============================================================ -Goal: Research approaches to vector database indexing and recommend - the best approach for our ... - ---- Generating Plan --- - ID: vector-db-indexing-research-plan - Goal Summary: Research vector database indexing approaches and recommend the best for 10M docu... - Steps: 11 - Requirements: 7 - Hypotheses: 2 - Step types: {"research":4,"synthesize":5,"experiment":2} - ---- Validation --- - Valid: true - Errors: 0 - ---- Topology Analysis --- - Entry points: [S1] - Exit points: [S11] - Critical path: 8 steps - Parallel groups: 8 - ---- Deterministic Scores --- - Overall: 92.5% - Structure: 85.9% - Coverage: 92.9% - Experiment Rigor: 92.5% - Unknowns Coverage: 100.0% - ---- Expected Characteristics Check --- - Issues: - - Unexpected hypotheses: 2 - - Unexpected experiment steps: 2 - - (LLM scorers skipped — set RUN_LLM_SCORERS=true to enable) - - Duration: 13.9s -``` - -**Note**: The LLM generated hypotheses and experiments that the fixture didn't expect. This is not a validation failure — the plan is valid, just more thorough than the minimum expected. - -
- -
-hypothesis-validation (15.4s) — PASS - -``` -============================================================ - FIXTURE: hypothesis-validation -============================================================ -Goal: Test whether fine-tuning a small LLM (e.g., Llama 3 8B) on - domain-specific data outperfo... - ---- Generating Plan --- - ID: entity-extraction-llm-comparison-plan - Goal Summary: Compare fine-tuned small LLM vs. few-shot large LLM for entity extraction.... - Steps: 12 - Requirements: 4 - Hypotheses: 2 - Step types: {"research":3,"synthesize":3,"experiment":3,"develop":3} - ---- Validation --- - Valid: true - Errors: 0 - ---- Topology Analysis --- - Entry points: [S1, S2, S3] - Exit points: [S12] - Critical path: 8 steps - Parallel groups: 8 - ---- Deterministic Scores --- - Overall: 95.3% - Structure: 86.0% - Coverage: 100.0% - Experiment Rigor: 95.0% - Unknowns Coverage: 100.0% - ---- Expected Characteristics Check --- - All expected characteristics met - - (LLM scorers skipped — set RUN_LLM_SCORERS=true to enable) - - Duration: 15.4s -``` - -
- -
-ct-database-goal (15.8s) — FAIL - -``` -============================================================ - FIXTURE: ct-database-goal -============================================================ -Goal: Create a backend language and database that is natively aligned - with category-theoretica... - ---- Generating Plan --- - ID: ct-db-backend-plan - Goal Summary: Create a backend language and database natively aligned with category theory, su... - Steps: 17 - Requirements: 8 - Hypotheses: 4 - Step types: {"research":4,"synthesize":8,"experiment":4,"develop":1} - ---- Validation --- - Valid: false - Errors: 1 - [MISSING_PREREGISTERED_COMMITMENTS] Confirmatory experiment "S14" must have preregistered commitments - - Duration: 15.8s -``` - -**Failure Reason**: The LLM generated a confirmatory experiment (S14) without including `preregisteredCommitments`. This is a known issue — the prompt needs to more strongly emphasize this requirement, or a revision loop needs to catch and fix it. - -
- ---- - -## Summary Report Test - -
-Summary Report (49.0s) — runs all fixtures sequentially - -``` -============================================================ - SUMMARY REPORT -============================================================ - -Total: 4 fixtures -Successful: 3 -Failed: 1 - -Failures: - - ct-database-goal: Validation failed: Confirmatory experiment "S14" must have preregistered commitments - -Deterministic Scores: - Fixture | Overall | Structure | Coverage | Rigor | Unknowns - ------------------------------------------------------------------------------------- - summarize-papers | 93% | 77% | 100% | 100% | 93% - explore-and-recommend | 92% | 86% | 93% | 93% | 100% - hypothesis-validation | 95% | 86% | 100% | 95% | 100% - -Total duration: 49.0s -``` - -
- ---- - -## Analysis - -### What's Working - -1. **Schema-LLM alignment is good** — 3/4 plans pass validation on first try -2. **Deterministic scores are high** (92-95%) indicating quality plans -3. **Step type variety** — LLM uses all 4 step types appropriately -4. **Unknowns coverage** — LLM consistently produces good epistemic documentation - -### Known Issue - -The `ct-database-goal` fixture fails due to **MISSING_PREREGISTERED_COMMITMENTS** — the LLM generates confirmatory experiments without the required `preregisteredCommitments` array. - -**Root cause**: The prompt instruction about preregisteredCommitments may not be prominent enough for complex plans. - -**Potential fixes**: - -1. Strengthen prompt wording around preregisteredCommitments requirement -2. Implement revision workflow loop (validator feedback → regenerate) -3. Add few-shot example showing proper confirmatory experiment structure - -### Next Steps - -See `PLAN-task-decomposition.md` Section 18 for the revision workflow implementation plan. diff --git a/apps/hash-ai-agent/_ai/plans/PLAN-task-decomposition.md b/apps/hash-ai-agent/_ai/plans/PLAN-task-decomposition.md deleted file mode 100644 index 1253fe23273..00000000000 --- a/apps/hash-ai-agent/_ai/plans/PLAN-task-decomposition.md +++ /dev/null @@ -1,1066 +0,0 @@ -# Task Decomposition & Planning Framework — Implementation Plan - -## Document Info - -- **Created**: 2024-12-16 -- **Updated**: 2024-12-17 -- **Status**: Implementation Phase — Core infrastructure complete, E2E validation next -- **Location**: `apps/hash-ai-agent/docs/PLAN-task-decomposition.md` - ---- - -## 1. Overview - -### 1.1 Goal - -Build a framework for decomposing complex research & development goals into structured, executable plans using LLM-based planning agents. The primary focus is on **plan quality evaluation** — validating and scoring generated plans before any execution occurs. - -### 1.2 Key Insight - -Treat LLM planning as a "compiler front-end" that produces an **Intermediate Representation (IR)** — the `PlanSpec` — which can be validated, scored, and eventually compiled/interpreted into executable workflows. - -### 1.3 Approach: MVP First - -Based on reviewer feedback, we adopt an MVP-first approach: - -- **Start with 4 step types** (not 7) to reduce schema complexity for LLM structured output -- **Defer decision points** until basic flow works -- **Focus on plan quality scoring** — stub execution has limited ROI -- **Get end-to-end flow working** before adding complexity - -### 1.4 Domain Focus - -Technical/mathematical research goals that flow through to development, including: - -- Research phases (parallelizable) -- Hypothesis generation and testing -- Experimentation (with uncertain outcomes) -- Synthesis and evaluation -- Development and implementation - ---- - -## 2. Architecture - -### 2.1 Three-Level Model - -``` -┌─────────────────────────────────────────────────────────────────────────────┐ -│ LEVEL 3: SUPERVISOR (future scope) │ -│ • Monitors overall progress against original goal │ -│ • Can trigger re-planning if things go off-track │ -│ • Same role as "Reviewer" — gates plan approval │ -└─────────────────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────────────────┐ -│ LEVEL 2: PLAN DESIGNER + REVIEWER ◀── CURRENT FOCUS │ -│ • Designer: Decomposes goal → PlanSpec (IR) │ -│ • Validator: Structural checks (deterministic) │ -│ • Supervisor: Approves/rejects plan (LLM judge) │ -│ • Loop: Design → Validate → Review → Revise (until approved) │ -└─────────────────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────────────────┐ -│ LEVEL 1: STEP EXECUTION (deferred — low priority) │ -│ • Interpreted execution: dountil loop with step function │ -│ • Stub executors: template-based mock outputs │ -│ • Proves control flow (parallel, branching, etc.) works │ -└─────────────────────────────────────────────────────────────────────────────┘ -``` - -### 2.2 Planning Workflow - -``` -Goal + Context - │ - ▼ -┌──────────────┐ ┌──────────────┐ ┌──────────────┐ -│ Planner │ ──▶ │ Validator │ ──▶ │ Supervisor │ -│ Agent │ │ (structural) │ │ (approval) │ -└──────────────┘ └──────────────┘ └──────────────┘ - │ │ │ - │ │ ▼ - │ │ Approved? ──▶ Output PlanSpec - │ │ │ - │ ◀────────────────────┘ - │ (feedback) - ◀─────────────────────────────┘ - (revision loop, max 3 attempts) -``` - -### 2.3 Execution Model (Interpreted) — Future - -Rather than compiling PlanSpec to static Mastra workflows, we use an **interpreter pattern**: - -```typescript -createWorkflow(...) - .then(initializeExecutionStateStep) - .dountil( - interpreterStep, // Reads state, picks next action, executes, updates state - async ({ inputData }) => inputData.allStepsComplete || inputData.iterations > 50 - ) - .then(finalizeExecutionStep) - .commit(); -``` - -This enables bounded dynamism — the loop structure is static, but the step function can make runtime decisions based on plan topology and execution state. - -**Note**: Stub execution is deferred and low priority. The real value is in plan quality scoring, not proving control flow with mocks. - ---- - -## 3. Step Type Taxonomy - -### 3.1 MVP Step Types (v1) - -| Type | Category | Description | Parallelizable | -| ------------ | --------- | -------------------------------------------- | -------------- | -| `research` | Strategic | Gather existing knowledge | Yes | -| `synthesize` | Strategic | Combine results OR evaluate against criteria | No | -| `experiment` | Tactical | Test hypothesis empirically | Yes | -| `develop` | Tactical | Build/implement something | Sometimes | - -### 3.2 Future Step Types - -| Type | Category | Description | Notes | -| ------------- | --------- | ------------------------------------------ | ------------------------------ | -| `hypothesize` | Strategic | Generate testable hypotheses from findings | Currently implicit in workflow | -| `transform` | Tactical | Pure data manipulation | Can be done via `develop` | - -### 3.3 Subsumed Types - -- **`assess`**: Subsumed by `synthesize` with `mode: 'evaluative'` - -### 3.4 Synthesis Modes - -```typescript -type SynthesisMode = 'integrative' | 'evaluative'; -// integrative: Combine findings from multiple sources -// evaluative: Judge results against criteria (subsumes old "assess") -``` - -### 3.5 Experiment Modes - -```typescript -type ExperimentMode = 'exploratory' | 'confirmatory'; -// exploratory: Hypothesis generation, flexible analysis, discovering patterns -// confirmatory: Preregistered design, locked analysis plan, testing specific predictions -``` - -**Key distinction**: Confirmatory experiments require `preregisteredCommitments` — decisions locked before seeing outcomes. This reduces "researcher degrees of freedom" and makes results more credible. - ---- - -## 4. PlanSpec Schema (IR) - -### 4.1 MVP Schema (v1) - -```typescript -// schemas/plan-spec.ts - -import { z } from "zod"; - -// === AIM TYPE (optional enrichment) === -// Not mutually exclusive, so weak signal for inference -// Include for now, evaluate usefulness later -const zAimType = z.enum(["describe", "explain", "predict", "intervene"]); - -// === REQUIREMENTS === -const zRequirement = z.object({ - id: z.string(), - description: z.string(), - priority: z.enum(["must", "should", "could"]), -}); - -// === HYPOTHESES === -// Hypotheses are first-class citizens, not buried in experiment descriptions -const zHypothesis = z.object({ - id: z.string(), - statement: z.string(), - assumptions: z.array(z.string()), - testableVia: z.string(), - status: z - .enum(["untested", "testing", "supported", "refuted", "inconclusive"]) - .default("untested"), -}); - -// === UNKNOWNS MAP (epistemically rigorous) === -// Partition based on scientific uncertainty principles -const zUnknownsMap = z.object({ - // High-confidence facts we're building on - knownKnowns: z.array(z.string()), - - // Explicit questions we know we need to answer - knownUnknowns: z.array(z.string()), - - // What would surprise us + how we'd detect it - unknownUnknowns: z.array( - z.object({ - potentialSurprise: z.string(), - detectionSignal: z.string(), // "How would we notice?" - }) - ), - - // What others would need to see to scrutinize our claims - // (Science depends on communal scrutiny, not private conviction) - communityCheck: z.string(), -}); - -// === DATA CONTRACTS === -const zDataContract = z.object({ - name: z.string(), - description: z.string(), - fromStepId: z.string().optional(), -}); - -// === EVALUATION CRITERIA === -const zEvalCriteria = z.object({ - successCondition: z.string(), - failureCondition: z.string().optional(), -}); - -// === EXECUTOR BINDING === -const zExecutor = z.discriminatedUnion("kind", [ - z.object({ kind: z.literal("agent"), ref: z.string() }), - z.object({ kind: z.literal("tool"), ref: z.string() }), - z.object({ kind: z.literal("workflow"), ref: z.string() }), - z.object({ kind: z.literal("human") }), -]); - -// === BASE STEP === -const zBaseStep = z.object({ - id: z.string(), - description: z.string(), - dependsOn: z.array(z.string()), - requirementIds: z.array(z.string()), - inputs: z.array(zDataContract), - outputs: z.array(zDataContract), - evalCriteria: zEvalCriteria.optional(), - executor: zExecutor, -}); - -// === RESEARCH STEP === -const zResearchStep = zBaseStep.extend({ - type: z.literal("research"), - query: z.string(), - stoppingRule: z.string(), // What "done" means for this research - parallelizable: z.literal(true).default(true), -}); - -// === SYNTHESIZE STEP === -// Subsumes old "assess" type via evaluative mode -const zSynthesizeStep = zBaseStep.extend({ - type: z.literal("synthesize"), - mode: z.enum(["integrative", "evaluative"]), - inputStepIds: z.array(z.string()), - // Required if mode === 'evaluative' - evaluateAgainst: z.array(z.string()).optional(), - parallelizable: z.literal(false).default(false), -}); - -// === EXPERIMENT STEP === -const zExperimentStep = zBaseStep.extend({ - type: z.literal("experiment"), - mode: z.enum(["exploratory", "confirmatory"]), - hypothesisIds: z.array(z.string()), - procedure: z.string(), - expectedOutcomes: z.array(z.string()), - successCriteria: z.array(z.string()), - // Required if mode === 'confirmatory' - // Decisions locked before seeing outcomes - preregisteredCommitments: z.array(z.string()).optional(), - parallelizable: z.literal(true).default(true), -}); - -// === DEVELOP STEP === -const zDevelopStep = zBaseStep.extend({ - type: z.literal("develop"), - specification: z.string(), - deliverables: z.array(z.string()), - parallelizable: z.boolean().default(false), -}); - -// === PLAN STEP (discriminated union) === -const zPlanStep = z.discriminatedUnion("type", [ - zResearchStep, - zSynthesizeStep, - zExperimentStep, - zDevelopStep, -]); - -// === MVP PLAN SPEC === -export const zPlanSpec = z.object({ - id: z.string(), - goalSummary: z.string(), - - // Optional enrichment — not mutually exclusive categories - aimType: zAimType.optional(), - - requirements: z.array(zRequirement), - hypotheses: z.array(zHypothesis), - steps: z.array(zPlanStep), - unknownsMap: zUnknownsMap, - - // No decision points in MVP - - estimatedComplexity: z - .enum(["low", "medium", "high", "very-high"]) - .optional(), -}); - -export type PlanSpec = z.infer; -export type PlanStep = z.infer; -export type Requirement = z.infer; -export type Hypothesis = z.infer; -export type UnknownsMap = z.infer; -``` - -### 4.2 Full Schema Additions (Future) - -The following would extend the MVP schema in future iterations: - -#### Additional Step Types - -```typescript -// Hypothesize step — currently implicit in workflow -const zHypothesizeStep = zBaseStep.extend({ - type: z.literal("hypothesize"), - basedOn: z.array(z.string()), // Step IDs that inform hypothesis - targetUnknowns: z.array(z.string()), // Which unknowns this addresses -}); - -// Transform step — pure data manipulation -const zTransformStep = zBaseStep.extend({ - type: z.literal("transform"), - transformation: z.string(), -}); -``` - -#### Decision Points - -```typescript -const zDecisionType = z.discriminatedUnion("type", [ - // Static branching based on conditions - z.object({ - type: z.literal("branch"), - conditions: z.array(z.object({ - condition: z.string(), - thenStepId: z.string(), - })), - defaultStepId: z.string().optional(), - }), - - // LLM supervisor makes decision at runtime - z.object({ - type: z.literal("supervisor-decision"), - question: z.string(), - possibleActions: z.array(z.object({ - id: z.string(), - description: z.string(), - enablesStepIds: z.array(z.string()).optional(), - disablesStepIds: z.array(z.string()).optional(), - triggersReplanning: z.boolean().optional(), - })), - }), - - // Human-in-the-loop decision - z.object({ - type: z.literal("human-decision"), - question: z.string(), - options: z.array(z.string()), - timeout: z.string().optional(), - }), -]); - -const zDecisionPoint = z.object({ - id: z.string(), - afterStepId: z.string(), - question: z.string(), - decisionType: zDecisionType, -}); -``` - -#### Enriched Experiment Design - -For rigorous scientific experiments (especially confirmatory): - -```typescript -const zEnrichedExperimentStep = zExperimentStep.extend({ - // Nuisance factors — variables that affect outcomes but aren't targets - nuisanceFactors: z.array(z.string()), - - // "Block what you can, randomize what you cannot" - blockingPlan: z.string().optional(), // For controllable nuisance factors - randomizationPlan: z.string().optional(), // For what remains - - // Replication intent - replicationPlan: z.object({ - unitOfReplication: z.string(), - sampleSizeRationale: z.string().optional(), - }).optional(), - - // Known threats to validity - threats: z.array(z.string()), // Confounds, leakage, missing data, drift - - // Statistical approach - analysisPlan: z.string(), - primaryMetric: z.string(), -}); -``` - -#### Phase Concept - -Explicit phase labels to validate step ordering: - -```typescript -const zPhase = z.enum([ - "exploration", // Research steps dominate - "hypothesis-formation", // Hypothesize + early synthesize - "experimentation", // Experiment + assess cycles - "development", // Develop + transform steps - "synthesis", // Final synthesize steps -]); - -// Add to base step: -// phase: zPhase.optional(), -``` - -#### Compound Steps (Patterns) - -Encapsulated recurring patterns: - -```typescript -const zCompoundStep = z.discriminatedUnion("pattern", [ - z.object({ - pattern: z.literal("parallel-research-synthesize"), - researchQueries: z.array(z.string()), - synthesisMode: z.enum(["integrative", "evaluative"]), - }), - z.object({ - pattern: z.literal("experiment-assess-decide"), - hypothesisId: z.string(), - maxIterations: z.number(), - }), -]); -``` - ---- - -## 5. Available Agents - -### 5.1 Capability Profiles - -Structured profiles help the planner reason about executor assignment: - -```typescript -// constants.ts - -export const AVAILABLE_AGENTS = { - // Research & Discovery - "literature-searcher": { - description: "Searches academic papers and technical documentation", - canHandle: ["research"], - inputs: ["query", "sources?"], - outputs: ["papers", "summaries"], - }, - "paper-summarizer": { - description: "Reads and summarizes academic papers", - canHandle: ["research"], - inputs: ["paper"], - outputs: ["summary", "keyFindings"], - }, - "concept-explainer": { - description: "Explains technical concepts at varying depths", - canHandle: ["research", "synthesize"], - inputs: ["concept", "targetAudience?"], - outputs: ["explanation"], - }, - - // Analysis & Synthesis - "result-synthesizer": { - description: "Combines findings from multiple sources", - canHandle: ["synthesize"], - inputs: ["findings[]"], - outputs: ["synthesis", "comparison?"], - }, - "hypothesis-generator": { - description: "Generates testable hypotheses from findings", - canHandle: ["synthesize"], // integrative mode leading to hypotheses - inputs: ["findings", "constraints"], - outputs: ["hypotheses"], - }, - "progress-evaluator": { - description: "Assesses current state against goals and criteria", - canHandle: ["synthesize"], // evaluative mode - inputs: ["results", "criteria"], - outputs: ["assessment", "gaps", "recommendations"], - }, - - // Experimentation - "experiment-designer": { - description: "Designs experimental procedures with controls", - canHandle: ["experiment"], - inputs: ["hypothesis", "constraints"], - outputs: ["experimentDesign", "protocol"], - }, - - // Implementation - "code-explorer": { - description: "Navigates and explains existing codebases", - canHandle: ["research"], - inputs: ["codebase", "query"], - outputs: ["explanation", "relevantFiles"], - }, - "code-writer": { - description: "Implements algorithms and prototypes", - canHandle: ["develop", "experiment"], - inputs: ["spec", "context"], - outputs: ["code", "tests?"], - }, - "code-reviewer": { - description: "Reviews code for correctness and quality", - canHandle: ["synthesize"], // evaluative mode - inputs: ["code", "criteria"], - outputs: ["review", "issues"], - }, -} as const; - -export type AgentRef = keyof typeof AVAILABLE_AGENTS; -``` - ---- - -## 6. File Structure - -``` -apps/hash-ai-agent/src/mastra/ -├── schemas/ -│ └── plan-spec.ts # PlanSpec IR schema (Zod) — MVP -│ -├── agents/ -│ ├── planner-agent.ts # Goal → PlanSpec (structured output) -│ └── supervisor-agent.ts # Plan review/approval -│ -├── workflows/ -│ ├── planning-workflow.ts # Plan → Validate → Approve loop -│ └── stub-execution-workflow.ts # Interpreted execution (deferred) -│ -├── steps/ -│ ├── extract-requirements-step.ts # Goal → Requirements list -│ ├── generate-plan-step.ts # Requirements → PlanSpec -│ ├── validate-plan-step.ts # Structural validation -│ ├── supervisor-review-step.ts # LLM approval gate -│ └── execution/ # (deferred) -│ ├── interpreter-step.ts -│ └── stub-executors.ts -│ -├── scorers/ -│ ├── plan-structure-scorer.ts # DAG validity, refs exist (deterministic) -│ ├── plan-coverage-scorer.ts # Requirements mapped to steps (deterministic) -│ ├── plan-testability-scorer.ts # Hypotheses can be tested (LLM) -│ ├── plan-granularity-scorer.ts # Steps appropriately scoped (LLM) -│ ├── experiment-rigor-scorer.ts # Confirmatory has preregistration (deterministic) -│ └── unknowns-coverage-scorer.ts # All unknown categories populated (deterministic) -│ -├── tools/ -│ ├── plan-validator.ts # Deterministic structural checks -│ └── topology-analyzer.ts # Find parallel groups, critical path -│ -├── fixtures/ -│ └── decomposition-prompts/ -│ ├── index.ts # Exports all fixtures -│ │ -│ │ # Positive fixtures (ordered by complexity) -│ ├── summarize-papers.ts # Linear, no experiments -│ ├── explore-and-recommend.ts # Parallel research → synthesize -│ ├── hypothesis-validation.ts # Research → experiment → synthesize -│ ├── ct-database-goal.ts # Full complexity (aspirational) -│ │ -│ │ # Negative fixtures (validation tests) -│ ├── invalid-cycle.ts # Steps form a cycle -│ ├── invalid-missing-ref.ts # dependsOn references non-existent step -│ ├── invalid-orphan-experiment.ts # Experiment without hypothesis -│ └── invalid-empty-plan.ts # Goal with no steps -│ -└── constants.ts # Available agents, models, etc. -``` - ---- - -## 7. Implementation Phases - -### Phase 1: Schema & Validation - -1. **`schemas/plan-spec.ts`** — MVP PlanSpec schema with 4 step types -2. **`constants.ts`** — Available agents with capability profiles -3. **`tools/plan-validator.ts`** — Deterministic structural checks: - - All `dependsOn` refs exist - - All `executor.ref` values in allowlist - - DAG is acyclic - - All `hypothesisIds` exist - - All `requirementIds` exist - - Confirmatory experiments have `preregisteredCommitments` - - Evaluative synthesize steps have `evaluateAgainst` -4. **`tools/topology-analyzer.ts`** — Analyze plan structure: - - Identify parallelizable step groups - - Compute critical path - - Detect bottlenecks - -### Phase 2: Fixtures - -1. **Positive fixtures** (ordered by complexity): - - `summarize-papers.ts` — Linear flow, no experiments - - `explore-and-recommend.ts` — Parallel research → synthesize - - `hypothesis-validation.ts` — Research → experiment → evaluative synthesize - - `ct-database-goal.ts` — Full R&D cycle (aspirational target) - -2. **Negative fixtures** (validation tests): - - `invalid-cycle.ts` — Steps that form a cycle - - `invalid-missing-ref.ts` — dependsOn references non-existent step - - `invalid-orphan-experiment.ts` — Experiment without hypothesis reference - - `invalid-empty-plan.ts` — Goal with no steps - -### Phase 3: Planner Agent - -1. **`agents/planner-agent.ts`** — Core planning agent: - - Instructions explaining step types, agents, patterns - - Structured output with `zPlanSpec` - - Available agents with capability profiles in system prompt - - See Section 15 for prompt strategy details - -### Phase 4: Scorers - -1. **Deterministic scorers**: - - `plan-structure-scorer.ts` — DAG valid, refs exist, no orphans - - `plan-coverage-scorer.ts` — All requirements addressed - - `experiment-rigor-scorer.ts` — Confirmatory experiments have preregistration - - `unknowns-coverage-scorer.ts` — All unknown categories populated - -2. **LLM judge scorers**: - - `plan-testability-scorer.ts` — Hypotheses can actually be tested - - `plan-granularity-scorer.ts` — Steps appropriately scoped - -### Phase 5: Planning Workflow - -1. **`steps/extract-requirements-step.ts`** -2. **`steps/generate-plan-step.ts`** -3. **`steps/validate-plan-step.ts`** -4. **`steps/supervisor-review-step.ts`** -5. **`agents/supervisor-agent.ts`** -6. **`workflows/planning-workflow.ts`** - -### Phase 6: Stub Execution (Deferred — Low Priority) - -**Note**: Per reviewer feedback, stub execution has limited ROI. The real value is in plan quality scoring, not proving control flow with mocks. Implement only if needed. - -1. **`steps/execution/stub-executors.ts`** — Template-based mocks -2. **`steps/execution/interpreter-step.ts`** — Core loop body -3. **`workflows/stub-execution-workflow.ts`** — Interpreted execution - ---- - -## 8. Key Design Decisions - -| Decision | Choice | Rationale | -| ----------------- | -------------------------------- | ----------------------------------------------------- | -| Schema complexity | MVP-first (4 step types) | LLMs struggle with deeply nested discriminated unions | -| Execution mode | Interpreted (deferred) | Supports dynamism, but plan quality is primary focus | -| Stub executors | Low priority | Plan quality scoring is the real signal | -| Plan evaluation | LLM judge + structural | No single "correct" decomposition | -| Hypotheses | Explicit top-level + referenced | Makes scientific structure visible | -| Unknowns | Epistemically rigorous partition | Surfaces uncertainty rather than hiding it | -| Experiment modes | Exploratory vs confirmatory | Reduces researcher degrees of freedom | -| Synthesis modes | Integrative vs evaluative | Subsumes "assess" step type | -| Decision points | Deferred to v2 | Simplifies MVP | - ---- - -## 9. Execution State Shape (Future) - -```typescript -interface ExecutionState { - plan: PlanSpec; - completedStepIds: string[]; - pendingStepIds: string[]; - stepResults: Record; - hypothesisStatuses: Record; - currentPhase: "research" | "experiment" | "synthesize" | "develop"; - iterations: number; - decisionLog: Array<{ stepId: string; decision: string; reason: string }>; -} -``` - ---- - -## 10. Evaluation Strategy - -### 10.1 Deterministic Scorers - -| Scorer | Measures | -| ------------------- | --------------------------------------------------------------- | -| `plan-structure` | DAG valid, refs exist, no orphans | -| `plan-coverage` | All requirements addressed by steps | -| `experiment-rigor` | Confirmatory experiments have preregistration | -| `unknowns-coverage` | All three unknown categories populated, community check present | - -### 10.2 LLM Judge Scorers - -| Scorer | Measures | -| ------------------- | ---------------------------------------------------------- | -| `plan-testability` | Hypotheses can actually be tested | -| `plan-granularity` | Steps appropriately scoped (not too broad, not too narrow) | -| `plan-coherence` | Steps make sense together | -| `plan-completeness` | No obvious gaps for the goal | - -### 10.3 Phase 1 Approach - -Manual inspection initially — no automated threshold assertions. As we gather data on plan quality, we can establish baselines and add automated checks. - ---- - -## 11. Test Fixtures - -### 11.1 Positive Fixtures - -#### Simple Linear: Summarize Papers - -```typescript -export const summarizePapersGoal = { - id: "summarize-papers", - goal: `Summarize 3 recent papers on retrieval-augmented generation (RAG) - and produce a comparison table of their approaches.`, - context: `We need to understand the current landscape of RAG techniques - for an internal tech review.`, - expectedCharacteristics: { - shouldHaveHypotheses: false, - shouldHaveExperiments: false, - shouldHaveParallelResearch: true, - minSteps: 3, - maxSteps: 6, - expectedStepTypes: ["research", "synthesize"], - }, -}; -``` - -#### Parallel Research: Explore and Recommend - -```typescript -export const exploreAndRecommendGoal = { - id: "explore-and-recommend", - goal: `Research approaches to vector database indexing and recommend - the best approach for our use case (10M documents, low latency).`, - context: `We're evaluating vector databases for a semantic search feature. - Need to understand tradeoffs between HNSW, IVF, and other approaches.`, - expectedCharacteristics: { - shouldHaveHypotheses: false, - shouldHaveExperiments: false, - shouldHaveParallelResearch: true, - minSteps: 4, - expectedStepTypes: ["research", "synthesize"], - shouldHaveEvaluativeSynthesize: true, - }, -}; -``` - -#### Hypothesis Validation - -```typescript -export const hypothesisValidationGoal = { - id: "hypothesis-validation", - goal: `Test whether fine-tuning a small LLM on domain-specific data - outperforms few-shot prompting with a larger model for our - entity extraction task.`, - context: `We have 5000 labeled examples. Need to determine the most - cost-effective approach for production deployment.`, - expectedCharacteristics: { - shouldHaveHypotheses: true, - shouldHaveExperiments: true, - shouldHaveParallelResearch: false, - minSteps: 5, - expectedStepTypes: ["research", "experiment", "synthesize"], - shouldHaveConfirmatoryExperiment: true, - }, -}; -``` - -#### Full Complexity: CT Database - -```typescript -export const ctDatabaseGoal = { - id: "ct-database", - goal: `Create a backend language and database that is natively aligned with - category-theoretical expressions. This should support objects, morphisms, - functors, and natural transformations as first-class concepts, with - query performance competitive with traditional databases.`, - context: `We're exploring whether CT primitives can serve as a more natural - foundation for data modeling than relational or document models. - Key unknowns include performance characteristics and expressiveness - tradeoffs.`, - expectedCharacteristics: { - shouldHaveHypotheses: true, - shouldHaveExperiments: true, - shouldHaveParallelResearch: true, - minSteps: 8, - expectedStepTypes: ["research", "experiment", "synthesize", "develop"], - shouldSurfaceUnknowns: true, - }, -}; -``` - -### 11.2 Negative Fixtures - -```typescript -// invalid-cycle.ts — Steps form a dependency cycle -export const invalidCycleFixture = { - steps: [ - { id: "step-1", dependsOn: ["step-3"] }, - { id: "step-2", dependsOn: ["step-1"] }, - { id: "step-3", dependsOn: ["step-2"] }, // Cycle! - ], - expectedError: "CYCLE_DETECTED", -}; - -// invalid-missing-ref.ts — Reference to non-existent step -export const invalidMissingRefFixture = { - steps: [ - { id: "step-1", dependsOn: ["step-999"] }, // Doesn't exist! - ], - expectedError: "INVALID_STEP_REFERENCE", -}; - -// invalid-orphan-experiment.ts — Experiment without hypothesis -export const invalidOrphanExperimentFixture = { - hypotheses: [], - steps: [ - { type: "experiment", hypothesisIds: ["h1"] }, // h1 doesn't exist! - ], - expectedError: "INVALID_HYPOTHESIS_REFERENCE", -}; - -// invalid-empty-plan.ts — Goal with no steps -export const invalidEmptyPlanFixture = { - goalSummary: "Do something important", - steps: [], - expectedError: "EMPTY_PLAN", -}; -``` - ---- - -## 12. Open Questions / Future Work - -1. **Full dynamism**: The "workflow within workflow" pattern where the step function can modify state to effectively inject new steps. Would need to hook into Mastra's event streaming. - -2. **Runtime supervisor decisions**: Currently supervisor only validates pre-kickoff. Future: supervisor makes decisions during interpreted execution. - -3. **Human-in-the-loop**: Decision points with `type: "human-decision"` would use Mastra's suspend/resume. - -4. **Real executors**: Replace stubs with actual agent implementations. - -5. **Plan caching/versioning**: Store plans for comparison, track how plans evolve. - -6. **Phased generation**: If single-shot plan generation struggles with complex goals, try multi-phase approach: - - Phase A: Extract requirements → `Requirement[]` - - Phase B: Generate steps given requirements → `Step[]` - - Phase C: Assemble into full `PlanSpec` - - Tradeoff: More LLM calls, but simpler output schemas per call. - -7. **Hybrid compiled/interpreted execution**: Compile "stable" portions of the plan to static Mastra workflow shapes, use interpreter only for portions with decision points or uncertain outcomes. - ---- - -## 13. Revision Loop Configuration - -When revision is needed, configurable via workflow input: - -```typescript -inputSchema: z.object({ - goal: z.string(), - context: z.string().optional(), - revisionStrategy: z - .enum(["all-feedback", "latest-only"]) - .default("all-feedback"), - maxRevisionAttempts: z.number().default(3), -}); -``` - ---- - -## 14. Design Rationale (from Reviews) - -Key insights from review feedback that shaped this design: - -### Why MVP-First - -LLMs struggle with deeply nested discriminated unions in structured output. Starting with 4 step types (not 7) and deferring decision points reduces schema complexity and improves generation reliability. - -### Why Interpreted Execution is Deferred - -The real value is in plan quality scoring, not proving control flow. Stub execution has limited ROI — it proves the interpreter works but doesn't validate whether the plan makes sense. - -### Why Epistemically Rigorous Unknowns - -The `knownKnowns / knownUnknowns / unknownUnknowns` partition forces the planner to surface uncertainty rather than hallucinate confidence. The `communityCheck` field ensures plans include what others would need to scrutinize claims. - -### Why Confirmatory/Exploratory Split - -This distinction from scientific methodology reduces "researcher degrees of freedom." Confirmatory experiments with preregistered commitments are more credible because decisions are locked before seeing outcomes. - -### Why Separate Validation from Scoring - -Validation is deterministic (DAG acyclic, refs exist). Scoring is evaluative (plan coherence, granularity). Separating them enables fast-fail on structural issues before expensive LLM evaluation. - ---- - -## 15. Planner Prompt Strategy - -### 15.1 Input Injection - -| Element | Location | Rationale | -| ------------------ | ---------------------------- | ---------------------------------------- | -| Goal | User message | Primary input, should be prominent | -| Context | User message (after goal) | Supplements goal | -| Available agents | System prompt | Static context the planner reasons about | -| Constraints | User message (after context) | Goal-specific constraints | -| Schema description | System prompt | Defines output structure | - -### 15.2 Agent Presentation - -Available agents should be presented with capability profiles: - -``` -Available executors for your plan: - -RESEARCH: -- literature-searcher: Searches academic papers. Inputs: query, sources?. Outputs: papers, summaries. -- paper-summarizer: Summarizes papers. Inputs: paper. Outputs: summary, keyFindings. - -SYNTHESIZE: -- result-synthesizer: Combines findings. Inputs: findings[]. Outputs: synthesis. -- progress-evaluator: Assesses against criteria. Inputs: results, criteria. Outputs: assessment, gaps. - -EXPERIMENT: -- experiment-designer: Designs procedures with controls. Inputs: hypothesis, constraints. Outputs: design, protocol. - -DEVELOP: -- code-writer: Implements algorithms. Inputs: spec, context. Outputs: code, tests?. -``` - -### 15.3 Few-Shot Examples - -None initially. Add if quality issues emerge. When added, use simple examples that demonstrate: - -- Correct step type usage -- Proper dependency structure -- Hypothesis → experiment linking -- Unknowns map population - -### 15.4 Phased Generation (Alternative) - -If single-shot struggles, try: - -1. **Extract requirements**: Goal → `Requirement[]` (simple array output) -2. **Generate steps**: Requirements → `Step[]` (array of steps, no full plan) -3. **Populate unknowns**: Goal + Steps → `UnknownsMap` -4. **Assemble**: Combine into full `PlanSpec` - -Each phase has a simpler output schema, improving reliability at the cost of more LLM calls. - ---- - -## 16. Meta-Cognitive Templates - -See `docs/PROMPTS-meta-cognitive.md` for research-planning and experiment-design prompt templates that encode rigorous scientific reasoning patterns. These may be incorporated as "sub-modes" invoked during planning. - ---- - -## 17. Implementation Status - -### Completed (Phase 1-4) - -| Component | File | Status | Tests | -| ------------------------- | --------------------------------- | ---------- | -------- | -| PlanSpec schema | `schemas/plan-spec.ts` | ✅ Complete | — | -| Agent profiles | `constants.ts` | ✅ Complete | — | -| Plan validator | `tools/plan-validator.ts` | ✅ Complete | 25 tests | -| Topology analyzer | `tools/topology-analyzer.ts` | ✅ Complete | — | -| Planner agent | `agents/planner-agent.ts` | ✅ Complete | — | -| Positive fixtures (4) | `fixtures/decomposition-prompts/` | ✅ Complete | — | -| Negative fixtures | `tools/plan-validator.test.ts` | ✅ Complete | 25 tests | -| Deterministic scorers (4) | `scorers/plan-scorers.ts` | ✅ Complete | 23 tests | -| LLM judge scorers (3) | `scorers/plan-llm-scorers.ts` | ✅ Complete | 6 tests | - -### Not Yet Implemented - -| Component | File | Status | Notes | -| ------------------------ | ------------------------------------- | ------------- | -------------------------------------- | -| Planning workflow loop | `workflows/planning-workflow.ts` | ⚠️ Stub only | No `.dountil()` revision logic | -| Supervisor agent | `agents/supervisor-agent.ts` | ❌ Not started | LLM approval gate | -| End-to-end tests | `workflows/planning-workflow.test.ts` | ⚠️ Partial | Uses hand-crafted plans, not generated | -| Stub execution (Level 1) | — | ❌ Not started | Low priority | - ---- - -## 18. Next Steps - -### Phase 5A: End-to-End Validation Test - -Before implementing the full workflow loop, validate that `generatePlan()` works reliably with the full schema: - -1. **Create E2E test** (`workflows/planning-workflow.test.ts`): - - Call `generatePlan()` with each of the 4 fixtures - - Run `validatePlan()` on the output - - Run deterministic scorers on valid plans - - Optionally run LLM scorers (controlled by config flag) - - Log results for manual inspection - -2. **Config flag for LLM scorers**: - - ```typescript - const RUN_LLM_SCORERS = process.env.RUN_LLM_SCORERS === "true"; - ``` - - This allows quick iteration with deterministic scorers only, then full scoring when needed. - -3. **Expected outcomes**: - - Identify schema-vs-LLM-output mismatches - - Surface any structured output reliability issues - - May incidentally fix the ct-database-goal preregistration issue - -### Phase 5B: Planning Workflow with Revision Loop - -Once E2E validation passes reliably: - -1. **Implement `agents/supervisor-agent.ts`**: - - Reviews generated plans against goal - - Returns approval/rejection with feedback - - Structured output: `{ approved: boolean, feedback?: string, issues?: string[] }` - -2. **Implement full `workflows/planning-workflow.ts`**: - - `extractRequirementsStep` → `generatePlanStep` → `validatePlanStep` → `supervisorReviewStep` - - `.dountil()` loop with max 3 revision attempts - - Pass feedback to planner on rejection - -3. **End-to-end workflow tests**: - - Test full loop with fixtures - - Verify revision improves plan quality - - Test max-attempts bailout - -### Phase 6: Stub Execution (Deferred) - -Low priority. Only implement if needed to prove control flow patterns. - ---- - -## 19. Test Conventions - -- **Colocated tests**: Tests live alongside source files (e.g., `plan-validator.test.ts`) -- **Standard vitest naming**: Use `.test.ts` suffix (not `.ai.test.ts`) -- **LLM scorer toggle**: Use `RUN_LLM_SCORERS` env var to control expensive LLM evaluation -- **Timeouts**: LLM-calling tests should set appropriate timeouts (60-180s) - ---- - -_End of Plan Document_ diff --git a/apps/hash-ai-agent/_ai/plans/PR-task-decomposition-framework.md b/apps/hash-ai-agent/_ai/plans/PR-task-decomposition-framework.md deleted file mode 100644 index 2b60bafac71..00000000000 --- a/apps/hash-ai-agent/_ai/plans/PR-task-decomposition-framework.md +++ /dev/null @@ -1,144 +0,0 @@ -# PR: Task Decomposition & Planning Framework - -## 🌟 What is the purpose of this PR? - -Introduces a framework for decomposing complex R&D goals into structured, executable plans using LLM-based planning agents. The core insight is treating LLM planning as a "compiler front-end" that produces an **Intermediate Representation (IR)** — the `PlanSpec` — which can be validated, scored, and eventually compiled into executable workflows. - -This PR establishes the foundational infrastructure for plan generation and quality evaluation, with the goal of enabling autonomous research and development workflows. - -## 🔗 Related links - -- `agent/docs/PLAN-task-decomposition.md` — Full design document and implementation plan -- `agent/docs/E2E-test-results-2024-12-17.md` — Latest E2E test outputs - -## 🚫 Blocked by - -_None_ - -## 🔍 What does this change? - -### Core Schema & Types - -- **`schemas/plan-spec.ts`** — Full Zod schema for `PlanSpec` with 4 step types: - - `research` — Parallelizable information gathering - - `synthesize` — Combining findings (integrative) or evaluating results (evaluative) - - `experiment` — Testing hypotheses (exploratory or confirmatory with preregistration) - - `develop` — Building/implementing artifacts - -- **`schemas/planning-fixture.ts`** — Types for test fixtures (`PlanningFixture`, `ExpectedPlanCharacteristics`) - -- **`constants.ts`** — 12 agent capability profiles with `canHandle` mappings for executor assignment - -### Validation & Analysis - -- **`tools/plan-validator.ts`** — 12 structural validation checks: - - DAG validity (no cycles, valid references) - - Executor compatibility - - Preregistration requirements for confirmatory experiments - - Input/output consistency - -- **`tools/topology-analyzer.ts`** — DAG analysis utilities: - - Entry/exit point detection - - Critical path calculation - - Parallel group identification - -### Scoring System - -- **`scorers/plan-scorers.ts`** — 4 deterministic scorers (no LLM, fast): - - `scorePlanStructure` — DAG validity, parallelism, step type diversity - - `scorePlanCoverage` — Requirement/hypothesis coverage - - `scoreExperimentRigor` — Preregistration, success criteria - - `scoreUnknownsCoverage` — Epistemic completeness - -- **`scorers/plan-llm-scorers.ts`** — 3 LLM-based judges: - - `goalAlignmentScorer` — Does plan address the goal? - - `planGranularityScorer` — Are steps appropriately sized? - - `hypothesisTestabilityScorer` — Are hypotheses testable? - -### Planning Agent - -- **`agents/planner-agent.ts`** — `generatePlan(goal, context)` function that uses structured output to produce valid `PlanSpec` instances - -### Test Fixtures - -4 fixtures of increasing complexity in `fixtures/decomposition-prompts/`: - -| Fixture | Complexity | Step Types | -|---------|------------|------------| -| `summarize-papers` | Simple linear | research → synthesize | -| `explore-and-recommend` | Parallel research | research (parallel) → synthesize (evaluative) | -| `hypothesis-validation` | With experiments | research → experiment → synthesize | -| `ct-database-goal` | Full R&D cycle | All 4 types, hypotheses, experiments | - -### E2E Test Suite - -- **`workflows/planning-workflow.test.ts`** — Comprehensive E2E tests: - - Runs all 4 fixtures through the full pipeline - - Validates generated plans - - Runs deterministic scorers - - Optional LLM scorers via `RUN_LLM_SCORERS=true` - - Generates summary report with score table - -## Pre-Merge Checklist 🚀 - -### 🚢 Has this modified a publishable library? - -This PR: - -- [x] does not modify any publishable blocks or libraries, or modifications do not need publishing - -### 📜 Does this require a change to the docs? - -The changes in this PR: - -- [x] are internal and do not require a docs change - -### 🕸️ Does this require a change to the Turbo Graph? - -The changes in this PR: - -- [x] do not affect the execution graph - -## ⚠️ Known issues - -1. **ct-database-goal fixture fails validation** — The LLM occasionally generates confirmatory experiments without `preregisteredCommitments`. This is a known prompt engineering issue that will be addressed in the revision workflow. - -2. **explore-and-recommend generates unexpected content** — The LLM adds hypotheses and experiments not specified in the fixture expectations. This is valid behavior (more thorough than minimum), but indicates fixture expectations may need adjustment. - -## 🐾 Next steps - -Per `PLAN-task-decomposition.md` Section 18: - -1. **Revision workflow loop** — Implement `dountil` loop: generate → validate → feedback → regenerate (max 3 attempts) -2. **Supervisor agent** — LLM approval gate before plan finalization -3. **Prompt improvements** — Strengthen preregisteredCommitments requirement -4. **Stub execution** — Low priority, deferred - -## 🛡 What tests cover this? - -- `plan-validator.test.ts` — 25 negative fixture tests for validation -- `plan-scorers.test.ts` — 23 unit tests for deterministic scorers -- `plan-llm-scorers.test.ts` — 6 tests for LLM judges -- `fixtures.test.ts` — 4 fixture validation tests -- `planning-workflow.test.ts` — E2E pipeline tests (3/4 passing) - -## ❓ How to test this? - -1. Checkout the branch -2. `cd apps/hash-ai-agent` -3. Run unit tests: `npx vitest run src/mastra/scorers/plan-scorers.test.ts` -4. Run E2E tests: `npx vitest run src/mastra/workflows/planning-workflow.test.ts` -5. (Optional) Run with LLM scorers: `RUN_LLM_SCORERS=true npx vitest run src/mastra/workflows/planning-workflow.test.ts` - -## 📹 Demo - -See `agent/docs/E2E-test-results-2024-12-17.md` for full test output, including: - -``` -Deterministic Scores: - Fixture | Overall | Structure | Coverage | Rigor | Unknowns - ------------------------------------------------------------------------------------- - summarize-papers | 93% | 77% | 100% | 100% | 93% - explore-and-recommend | 92% | 86% | 93% | 93% | 100% - hypothesis-validation | 95% | 86% | 100% | 95% | 100% -``` diff --git a/apps/hash-ai-agent/_ai/plans/compiler-phase-1-done.md b/apps/hash-ai-agent/_ai/plans/compiler-phase-1-done.md deleted file mode 100644 index 4761110029d..00000000000 --- a/apps/hash-ai-agent/_ai/plans/compiler-phase-1-done.md +++ /dev/null @@ -1,39 +0,0 @@ -Phase 1 Complete! -I've successfully implemented the plan compiler infrastructure. Here's a summary: -Files Created -| File | Purpose | Lines | -| -------------------------------------- | ------------------------------------ | ----- | -| src/mastra/tools/mock-agent.ts | Deterministic mock agent for testing | ~350 | -| src/mastra/tools/plan-compiler.ts | Compiles PlanSpec → Mastra Workflow | ~540 | -| src/mastra/tools/plan-compiler.test.ts | Integration tests | ~730 | -Test Results -All 20 tests pass: -Compilation Tests (5): -- ✓ Compiles minimal valid plan -- ✓ Compiles linear plan with sequential dependencies -- ✓ Compiles plan with parallel steps -- ✓ Compiles diamond-shaped plan -- ✓ Compiles plan with mixed parallelism -Topology Analysis Tests (7): -- ✓ Correctly identifies entry points -- ✓ Correctly identifies exit points -- ✓ Correctly computes parallel groups for parallel plan -- ✓ Correctly computes parallel groups for diamond plan -- ✓ Correctly computes topological order for linear plan -- ✓ Correctly identifies critical path -- ✓ Correctly identifies parallelizable steps within groups -Execution Tests (4): -- ✓ Executes minimal plan and returns result -- ✓ Executes linear plan in correct order -- ✓ Executes parallel plan respecting dependencies -- ✓ Executes diamond plan respecting dependencies -Streaming Events Tests (4): -- ✓ Emits plan-start event -- ✓ Emits step-start and step-complete events -- ✓ Emits progress events -- ✓ Emits plan-complete event -Key Implementation Details -1. MockAgent - Returns deterministic responses based on step type, includes traceable __mock metadata -2. TopologyAnalyzer integration - Uses your existing analyzer for parallel groups and execution order -3. Streaming events - Six data-plan-* event types flow through writer.custom() -4. Fail-fast error handling - Steps throw on error, workflow stops diff --git a/apps/hash-ai-agent/_ai/plans/CONDITIONAL-BRANCHING.md b/apps/hash-ai-agent/_ai/wiki/conditional-branching.md similarity index 97% rename from apps/hash-ai-agent/_ai/plans/CONDITIONAL-BRANCHING.md rename to apps/hash-ai-agent/_ai/wiki/conditional-branching.md index 1b0887a8b2c..68f18afbbd1 100644 --- a/apps/hash-ai-agent/_ai/plans/CONDITIONAL-BRANCHING.md +++ b/apps/hash-ai-agent/_ai/wiki/conditional-branching.md @@ -1,8 +1,9 @@ # Conditional Branching in Plan Execution -> **Status**: Deferred to Phase 4 +> **Status**: Deferred — see [gaps-and-next-steps.md](./gaps-and-next-steps.md) > **Created**: 2024-12-18 -> **Context**: Plan compilation and execution infrastructure +> **Moved to wiki**: 2024-12-19 +> **Context**: Design options for runtime branching in plan execution ## Overview diff --git a/apps/hash-ai-agent/_ai/wiki/execution-state.md b/apps/hash-ai-agent/_ai/wiki/execution-state.md new file mode 100644 index 00000000000..f6f5e3fe7b8 --- /dev/null +++ b/apps/hash-ai-agent/_ai/wiki/execution-state.md @@ -0,0 +1,415 @@ +# Execution State: Accumulating Handoffs into Epistemic State + +> Formalizes how handoff packets fold into cumulative execution state. +> Captured 2024-12-19. See also: [handoff-packets.md](./handoff-packets.md) + +## Core Concept + +Handoffs are the **incremental unit of state change**. Each step produces a handoff; the orchestrator's job is to *fold* handoffs into cumulative execution state that tracks: + +- What we've learned (evidence ledger) +- What we still don't know (uncertainty inventory) +- What we've produced (artifact registry) +- What we didn't do (gaps registry) +- The sequence of contributions (handoff log / audit trail) + +## Execution State Shape + +```typescript +interface ExecutionState { + // === Plan reference (immutable unless re-planning) === + plan: PlanSpec; + + // === Step tracking === + completedStepIds: string[]; + pendingStepIds: string[]; // derived from plan topology + currentStepId: string | null; // for in-progress tracking + + // === Handoff accumulation (audit trail) === + handoffLog: Array<{ + stepId: string; + handoff: StepHandoff; + timestamp: number; + }>; + + // === Derived epistemic state (folded from handoffs) === + + // Evidence: observations with provenance + evidenceLedger: Array<{ + finding: string; + source?: string; + confidence?: number; + fromStepId: string; + }>; + + // Uncertainty: open questions raised by steps + uncertaintyInventory: Array<{ + question: string; + raisedByStepId: string; + status: "open" | "testing" | "resolved"; + resolvedByStepId?: string; + }>; + + // Artifacts: produced outputs with refs + artifactRegistry: Array<{ + artifact: string; + ref: string; + fromStepId: string; + }>; + + // Gaps: what wasn't done (informs future planning) + gapsRegistry: Array<{ + item: string; + reason: string; + fromStepId: string; + }>; + + // === Control flow state === + iterations: number; // for loop bounds + planComplete: boolean; // all steps done + needsReplanning: boolean; // trigger for re-plan branch + + // === Hypothesis tracking (updated by experiment handoffs) === + hypothesisStatuses: Record; +} +``` + +## State Initialization + +At plan execution start, initialize from the PlanSpec: + +```typescript +function initializeExecutionState(plan: PlanSpec): ExecutionState { + return { + plan, + completedStepIds: [], + pendingStepIds: plan.steps.map(s => s.id), + currentStepId: null, + handoffLog: [], + + // Start empty — populated by handoff folding + evidenceLedger: [], + uncertaintyInventory: [], + artifactRegistry: [], + gapsRegistry: [], + + iterations: 0, + planComplete: false, + needsReplanning: false, + + // Initialize hypothesis statuses from plan + hypothesisStatuses: Object.fromEntries( + plan.hypotheses.map(h => [h.id, { + status: h.status ?? "untested", + testedByStepIds: [], + evidenceStepIds: [], + }]) + ), + }; +} +``` + +## Fold Operation: Handoff → State + +After each step completes with a valid handoff, fold it into state: + +```typescript +function foldHandoff( + state: ExecutionState, + stepId: string, + handoff: StepHandoff +): ExecutionState { + const timestamp = Date.now(); + + return { + ...state, + + // Mark step complete + completedStepIds: [...state.completedStepIds, stepId], + pendingStepIds: state.pendingStepIds.filter(id => id !== stepId), + currentStepId: null, + + // Append to audit trail + handoffLog: [...state.handoffLog, { stepId, handoff, timestamp }], + + // Fold observations into evidence ledger + evidenceLedger: [ + ...state.evidenceLedger, + ...handoff.observed.map(obs => ({ + finding: obs.finding, + source: obs.source, + confidence: obs.confidence, + fromStepId: stepId, + })), + ], + + // Add highest-impact uncertainty as new known-unknown + uncertaintyInventory: [ + ...state.uncertaintyInventory, + { + question: handoff.highestImpactUncertainty, + raisedByStepId: stepId, + status: "open", + }, + ], + + // Register produced artifacts + artifactRegistry: [ + ...state.artifactRegistry, + ...handoff.changed.map(c => ({ + artifact: c.artifact, + ref: c.ref, + fromStepId: stepId, + })), + ], + + // Track acknowledged gaps + gapsRegistry: [ + ...state.gapsRegistry, + ...handoff.notDone.map(nd => ({ + item: nd.item, + reason: nd.reason, + fromStepId: stepId, + })), + ], + + iterations: state.iterations + 1, + }; +} +``` + +## Interpreter Loop Integration + +The execution state is the "mutable state" in the interpreter pattern from [gaps-and-next-steps.md](./gaps-and-next-steps.md): + +```typescript +const executionWorkflow = createWorkflow({ + id: "plan-execution", + inputSchema: z.object({ plan: zPlanSpec }), + outputSchema: zExecutionResult, +}) + // Initialize state from plan + .map(async ({ inputData }) => initializeExecutionState(inputData.plan)) + + // Interpreter loop: execute steps, fold handoffs, check termination + .dountil( + interpreterStep, + async ({ inputData }) => inputData.planComplete || inputData.needsReplanning + ) + + // Branch on outcome + .branch([ + [({ inputData }) => inputData.needsReplanning, replanStep], + [() => true, finalizeStep], + ]) + .commit(); +``` + +### Interpreter Step Logic + +```typescript +const interpreterStep = createStep({ + id: "interpreter", + inputSchema: zExecutionState, + outputSchema: zExecutionState, + execute: async ({ inputData }) => { + const state = inputData; + + // 1. Pick next step(s) based on topology and completed steps + const nextStepId = pickNextReadyStep(state); + if (!nextStepId) { + return { ...state, planComplete: true }; + } + + // 2. Get step definition from plan + const planStep = state.plan.steps.find(s => s.id === nextStepId)!; + + // 3. Build context from prior handoffs + const context = buildContextFromState(state, planStep); + + // 4. Execute step, expecting handoff-shaped output + const handoff = await executeStepAndGetHandoff(planStep, context); + + // 5. Fold handoff into state + const newState = foldHandoff(state, nextStepId, handoff); + + // 6. Check re-planning triggers + const needsReplanning = shouldReplan(newState, handoff); + + // 7. Check completion + const planComplete = newState.pendingStepIds.length === 0; + + return { ...newState, planComplete, needsReplanning }; + }, +}); +``` + +## Context Building for Successor Steps + +When executing a step, build context from accumulated state: + +```typescript +function buildContextFromState( + state: ExecutionState, + planStep: PlanStep +): StepContext { + // Get handoffs from dependency steps + const dependencyHandoffs = planStep.dependsOn + .map(depId => state.handoffLog.find(h => h.stepId === depId)) + .filter((h): h is NonNullable => h !== undefined); + + // Get relevant evidence (from dependencies or all) + const relevantEvidence = state.evidenceLedger.filter(e => + planStep.dependsOn.includes(e.fromStepId) + ); + + // Get current hypothesis statuses + const hypothesisContext = planStep.type === "experiment" + ? planStep.hypothesisIds.map(hid => ({ + id: hid, + ...state.hypothesisStatuses[hid], + })) + : []; + + // Include the "nextAgentShouldFirst" recommendations from dependencies + const recommendations = dependencyHandoffs + .map(h => h.handoff.nextAgentShouldFirst); + + return { + dependencyHandoffs, + relevantEvidence, + hypothesisContext, + recommendations, + openUncertainties: state.uncertaintyInventory.filter(u => u.status === "open"), + }; +} +``` + +## Re-planning Triggers + +Handoffs can signal that the current plan is no longer valid: + +```typescript +function shouldReplan(state: ExecutionState, handoff: StepHandoff): boolean { + // 1. Uncertainty invalidates a plan assumption (known-known) + const invalidatesAssumption = state.plan.unknownsMap.knownKnowns.some(kk => + handoff.highestImpactUncertainty.toLowerCase().includes(kk.toLowerCase()) + ); + + // 2. Critical gap accumulation threshold + const criticalGapCount = state.gapsRegistry.filter(g => + isCriticalGap(g, state.plan.requirements) + ).length; + const tooManyGaps = criticalGapCount > 3; // configurable threshold + + // 3. Hypothesis refuted that plan depends on + const refutedCriticalHypothesis = Object.entries(state.hypothesisStatuses) + .some(([hid, status]) => + status.status === "refuted" && isPlanCritical(hid, state.plan) + ); + + // 4. Explicit signal in handoff (future: structured field) + const explicitReplanRequest = handoff.highestImpactUncertainty + .toLowerCase().includes("need to replan"); + + return invalidatesAssumption || tooManyGaps || refutedCriticalHypothesis || explicitReplanRequest; +} +``` + +## Hypothesis Status Updates + +Experiment step handoffs should update hypothesis statuses: + +```typescript +function updateHypothesisStatuses( + state: ExecutionState, + experimentStepId: string, + handoff: StepHandoff, + planStep: ExperimentStep +): ExecutionState { + const updatedStatuses = { ...state.hypothesisStatuses }; + + for (const hid of planStep.hypothesisIds) { + const current = updatedStatuses[hid]; + if (!current) continue; + + // Determine new status from handoff observations + // (In practice, this might be a structured field in payload) + const newStatus = inferHypothesisStatus(handoff, hid); + + updatedStatuses[hid] = { + ...current, + status: newStatus, + testedByStepIds: [...current.testedByStepIds, experimentStepId], + evidenceStepIds: [...current.evidenceStepIds, experimentStepId], + }; + } + + return { ...state, hypothesisStatuses: updatedStatuses }; +} +``` + +## State Persistence + +For long-running execution with suspend/resume, state must be serializable: + +```typescript +// All fields are JSON-serializable by design +const serializedState = JSON.stringify(executionState); + +// Mastra's suspend() persists this automatically +await suspend({ reason: "Human approval required", state: executionState }); + +// On resume, state is restored +const { resumeData } = context; +const restoredState = resumeData.state as ExecutionState; +``` + +## Diagram: State Flow + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ Step S1 │───▶│ Step S2 │───▶│ Step S3 │ +└─────────────┘ └─────────────┘ └─────────────┘ + │ │ │ + ▼ ▼ ▼ + Handoff H1 Handoff H2 Handoff H3 + │ │ │ + └────────┬─────────┴─────────┬───────┘ + │ │ + ▼ ▼ + ┌─────────────────────────────────┐ + │ ExecutionState │ + ├─────────────────────────────────┤ + │ handoffLog: [H1, H2, H3] │ + │ evidenceLedger: [obs...] │ + │ uncertaintyInventory: [q...] │ + │ artifactRegistry: [a...] │ + │ gapsRegistry: [g...] │ + └─────────────────────────────────┘ + │ + ▼ + ┌───────────────┐ + │ Re-plan check │ + └───────────────┘ + │ + ┌───────────┴───────────┐ + ▼ ▼ + Continue plan Trigger re-plan +``` + +## Open Questions + +1. **Parallel step handoffs**: When multiple steps execute in parallel, how do we handle concurrent folds? Order may matter for uncertainty resolution. + +2. **Handoff validation**: Should there be a dedicated validator that checks handoff quality before folding? + +3. **State compaction**: As handoff log grows, may need summarization for context limits. How to preserve audit trail while compacting? + +4. **Uncertainty deduplication**: Multiple steps may raise similar uncertainties. How to detect and merge? + +5. **Confidence propagation**: When synthesize steps combine evidence, how do confidence scores aggregate? diff --git a/apps/hash-ai-agent/_ai/wiki/gaps-and-next-steps.md b/apps/hash-ai-agent/_ai/wiki/gaps-and-next-steps.md new file mode 100644 index 00000000000..aca40091caf --- /dev/null +++ b/apps/hash-ai-agent/_ai/wiki/gaps-and-next-steps.md @@ -0,0 +1,229 @@ +# Gaps & Next Steps + +> Living document tracking implementation gaps and planned work. +> Last updated: 2024-12-19 + +## Current State Summary + +The planning framework has: +- ✅ PlanSpec schema with 4 step types (research, synthesize, experiment, develop) +- ✅ Plan validation (structural checks) +- ✅ Deterministic scorers (structure, coverage, rigor, unknowns) +- ✅ LLM judge scorers (alignment, granularity, testability) +- ✅ Planner agent with structured output +- ✅ Planning workflow with revision loop (validate → feedback → regenerate) +- ✅ Plan compiler (PlanSpec → Mastra workflow) +- ✅ Topology analyzer (parallel groups, critical path) +- ✅ Mock agents for testing +- ✅ Streaming events for execution progress +- ✅ Clack-based demo for interactive visualization + +## Conceptual Advances (2024-12-19) + +New wiki documents capture significant design evolution: + +| Document | Concept | +|----------|---------| +| [handoff-packets.md](./handoff-packets.md) | Stop conditions via output contracts — step is "done" when it produces a valid handoff | +| [execution-state.md](./execution-state.md) | Cumulative state from folding handoffs — evidence ledger, uncertainty inventory, artifact registry | +| [meta-cognitive-prompts.md](./meta-cognitive-prompts.md) | Templates for uncertainty-first research and rigorous experiment design | +| [conditional-branching.md](./conditional-branching.md) | Design options for runtime branching (deferred) | + +These represent a shift toward **epistemically rigorous R&D orchestration** rather than simple task execution. + +--- + +## Priority 1: Handoff Packet Integration + +**Problem**: Current step outputs are unstructured (`outputs: DataContract[]` at plan-time, arbitrary objects at runtime). No standard for what constitutes a "complete" step contribution. + +**Solution**: Implement `StepHandoff` schema as the canonical output format: +- Every step produces: attempted, observed, changed, notDone, highestImpactUncertainty, nextAgentShouldFirst +- Handoff completeness becomes the stop condition +- Handoffs fold into execution state + +**Files to modify**: +- `schemas/plan-spec.ts` — Add `zStepHandoff` and related types +- `tools/plan-compiler.ts` — Update prompt building to require handoff format +- `tools/mock-agent.ts` — Return handoff-shaped mock responses + +**Complexity**: Medium + +--- + +## Priority 2: Execution State Schema + +**Problem**: No structured runtime state beyond what Mastra provides. Can't track evidence accumulation, uncertainty evolution, or audit trail across steps. + +**Solution**: Implement `ExecutionState` as described in [execution-state.md](./execution-state.md): +- Initialize from PlanSpec +- Fold handoffs after each step +- Track evidence ledger, uncertainty inventory, artifact registry, gaps registry +- Enable re-planning triggers + +**Files to create/modify**: +- `schemas/execution-state.ts` — New schema +- `tools/plan-compiler.ts` or new `tools/interpreter.ts` — State management + +**Complexity**: Medium-High + +--- + +## Priority 3: Synthetic Mock Agents + +**Problem**: Current mock agents return deterministic responses. This is good for testing compilation and flow, but doesn't test workflow dynamics under realistic variation. + +**Insight**: Need a middle ground between deterministic mocks and real long-running execution. + +**Solution**: "Synthetic mocking" — mock agents that make real LLM calls to generate realistic but synthetic step outputs: +- Takes step context (type, description, inputs) +- Generates plausible handoff packet via LLM +- Can simulate failures, unexpected findings, or re-planning triggers +- Enables testing of interpreter dynamics without real tasks + +```typescript +interface SyntheticMockConfig { + mode: "deterministic" | "synthetic" | "real"; + syntheticVariation?: "nominal" | "surprising" | "failing"; + llmModel?: string; // For synthetic mode +} +``` + +**Files to modify**: +- `tools/mock-agent.ts` — Add synthetic mode with LLM-backed generation + +**Complexity**: Low-Medium + +--- + +## Priority 4: Interpreter Pattern + +**Problem**: Compiled workflows have fixed shape at commit time. Can't support Level 3 dynamism (re-planning based on execution outcomes). + +**Solution**: Implement interpreter pattern as described in [execution-state.md](./execution-state.md): +```typescript +createWorkflow(...) + .map(initializeExecutionState) + .dountil(interpreterStep, ({ inputData }) => + inputData.planComplete || inputData.needsReplanning + ) + .branch([ + [({ inputData }) => inputData.needsReplanning, replanStep], + [() => true, finalizeStep], + ]) + .commit(); +``` + +The interpreter step: +- Picks next ready step(s) from topology +- Builds context from prior handoffs +- Executes step, expecting handoff output +- Folds handoff into state +- Checks re-planning triggers + +**Files to create**: +- `workflows/interpreted-execution.ts` — New interpreter-based execution workflow +- Could coexist with compiled approach for simpler plans + +**Complexity**: High + +--- + +## Priority 5: Score Threshold Quality Gate + +**Problem**: Revision loop only checks boolean `valid` flag. Structurally valid but mediocre plans pass immediately. + +**Solution**: Add composite score threshold to revision loop: +- After validation passes, run `scorePlanComposite()` +- Require `overall >= 0.85` (configurable) to exit loop +- If below threshold, build feedback from low-scoring areas + +**Files to modify**: +- `workflows/planning-workflow.ts` — Integrate scorer into loop condition + +**Complexity**: Low + +--- + +## Priority 6: Supervisor Agent + +**Problem**: No semantic review of plans against original goal. Validation is structural only. + +**Solution**: Implement supervisor agent as LLM approval gate: +- Reviews plan against goal +- Returns `{ approved: boolean, feedback?: string, issues?: string[] }` +- Integrates after validation + scoring in revision loop + +**Files to create**: +- `agents/supervisor-agent.ts` + +**Complexity**: Medium + +--- + +## Priority 7: Human-in-the-Loop Gates + +**Problem**: No support for human approval checkpoints during execution. + +**Solution**: Use Mastra's `suspend()`/`resume()` at key decision points: +- Post-design, pre-execution (human approves experimental design) +- Post-analysis, pre-interpretation (human validates analysis) +- Post-conclusion, pre-propagation (human checks confidence claims) + +**Integration**: Works naturally with interpreter pattern — interpreter can decide to suspend based on step type or confidence level. + +**Complexity**: Medium (infrastructure exists in Mastra) + +--- + +## Deferred / Low Priority + +### Conditional Branching (Level 1 Dynamism) +Static branching based on conditions in plan. Design options captured in [conditional-branching.md](./conditional-branching.md). Less urgent now that interpreter pattern handles higher levels of dynamism. + +### Real Agent Execution +Replacing mock agents with actual capable agents. Deferred until: +1. Handoff packet format is stable +2. Execution state management is solid +3. Quality of plan decomposition is validated + +--- + +## Three Levels of Execution Dynamism + +| Level | Description | Mastra Primitive | Status | +|-------|-------------|------------------|--------| +| **1: Static branching** | Pre-defined branches in plan | `.branch()` | Design captured, deferred | +| **2: Runtime decisions** | Agent evaluates outcomes, chooses path | Interpreter + handoff analysis | Priority 4 | +| **3: Re-planning** | Outcomes trigger plan revision | Interpreter + `generatePlan()` | Priority 4 | + +The interpreter pattern (Priority 4) unlocks both Level 2 and Level 3 dynamism. + +--- + +## Implementation Order Recommendation + +1. **Handoff packets** (Priority 1) — Foundation for everything else +2. **Synthetic mocks** (Priority 3) — Enables testing subsequent work +3. **Execution state** (Priority 2) — Requires handoffs +4. **Score threshold** (Priority 5) — Quick win for plan quality +5. **Interpreter** (Priority 4) — Requires execution state +6. **Supervisor** (Priority 6) — Can develop in parallel +7. **HITL gates** (Priority 7) — Builds on interpreter + +--- + +## Reference: Mastra Primitives Available + +From source exploration (2024-12-19): + +| Primitive | Purpose | Notes | +|-----------|---------|-------| +| `.dountil(step, condition)` | Loop until condition true | Step can be nested workflow | +| `.branch([...])` | Conditional routing | First matching condition wins | +| `suspend()` / `resumeData` | Pause/resume with persisted state | For HITL | +| `writer.custom()` | Emit streaming events | For progress tracking | +| `getStepResult(stepId)` | Read prior step outputs | For context building | +| `setState()` / `state` | Mutable step state | For accumulation | + +See also: [mastra-patterns.md](./mastra-patterns.md) diff --git a/apps/hash-ai-agent/_ai/wiki/handoff-packets.md b/apps/hash-ai-agent/_ai/wiki/handoff-packets.md new file mode 100644 index 00000000000..5c4a336afd3 --- /dev/null +++ b/apps/hash-ai-agent/_ai/wiki/handoff-packets.md @@ -0,0 +1,122 @@ +# Handoff Packets: Stop Conditions via Output Contracts + +> Insight derived from Anthropic's harness patterns + HN commentary on multi-agent delegation. +> Captured 2024-12-19. + +## Core Insight + +If you define what a delegate agent must hand off at the end of their task, you implicitly define when they're done. The handoff packet inverts the stop condition problem: + +- **Before**: "How do I know when I'm done pursuing X?" (open-ended, prone to premature exit or infinite loops) +- **After**: "Have I produced a complete contribution artifact?" (verifiable, bounded) + +The goal becomes not to pursue something to its ultimate possible end, but to fulfill the conditions of a good research step contribution. + +## Handoff Packet Structure + +Every delegate produces a standard structured object: + +| Field | Purpose | +|-------|---------| +| `attempted` | What the delegate tried to accomplish | +| `observed` | Findings with provenance (source) and confidence (0-1) | +| `changed` | Artifacts produced with references (commit hash, file path, URL) | +| `notDone` | What was skipped and why — forces acknowledgment of limits | +| `highestImpactUncertainty` | The most important open question after this step | +| `nextAgentShouldFirst` | Recommended first action for successor — forces continuity reasoning | +| `payload` | (optional) Step-type-specific data outputs | + +### Key Properties + +1. **Completeness as stop condition**: Step is "done" when handoff is well-formed, not when some external condition is satisfied or resources exhausted. + +2. **Forced reflection on gaps**: The `notDone` array prevents silent scope creep or premature termination — delegates must explicitly acknowledge what they didn't do. + +3. **Epistemic humility**: `highestImpactUncertainty` maintains honest uncertainty tracking across delegation boundaries. + +4. **Continuity**: `nextAgentShouldFirst` forces the delegate to reason about the broader plan context, not just their local task. + +5. **Provenance**: `observed` entries carry source and confidence, enabling evidence ledger updates and audit trails. + +## Relationship to Anthropic Patterns + +| Anthropic Pattern | Handoff Packet Analog | +|-------------------|----------------------| +| `progress.txt` | Accumulated handoffs form the progress log | +| "Read git log" orientation | `changed` provides artifact refs for successors | +| Self-verification before status change | Can't produce valid handoff without completing work | +| Incremental progress with clean-state | Each handoff is a clean contribution unit | + +## Schema Sketch (Zod) + +```typescript +export const zObservation = z.object({ + finding: z.string(), + source: z.string().optional(), + confidence: z.number().min(0).max(1).optional(), +}); + +export const zArtifactChange = z.object({ + artifact: z.string(), + ref: z.string(), // commit, path, URL +}); + +export const zNotDone = z.object({ + item: z.string(), + reason: z.string(), +}); + +export const zStepHandoff = z.object({ + attempted: z.string(), + observed: z.array(zObservation), + changed: z.array(zArtifactChange), + notDone: z.array(zNotDone), + highestImpactUncertainty: z.string(), + nextAgentShouldFirst: z.string(), + payload: z.record(z.string(), z.unknown()).optional(), +}); +``` + +## Integration Points + +### Plan-time vs Runtime + +| Schema | Role | +|--------|------| +| `outputs: DataContract[]` | Plan-time: what artifacts are *expected* | +| `evalCriteria` | Plan-time: success/failure conditions (may deprecate) | +| **`StepHandoff`** | Runtime: what was *actually produced* + epistemic metadata | + +The `outputs` field describes *intent*; the handoff describes *actuality*. Orchestrator can validate that `handoff.payload` contains expected `outputs` keys. + +### Execution State Accumulation + +Handoffs accumulate into execution state, enabling: +- Evidence ledger updates (from `observed` entries) +- Uncertainty inventory updates (from `highestImpactUncertainty`) +- Artifact tracking (from `changed` entries) +- Decision audit trail (from sequence of `attempted` + `notDone`) + +See: [Execution State Design](#) (TODO: create separate doc) + +## Specialized Roles and Handoffs + +Different agent roles may emphasize different handoff fields: + +| Role | Primary Contribution | +|------|---------------------| +| Literature scout | `observed` rich with sources, confidence scores | +| Methodologist | `payload` contains experimental design; `notDone` lists considered alternatives | +| Execution agent | `changed` rich with artifact refs; `observed` contains raw results | +| Skeptic/replicator | `notDone` emphasizes attempted-but-failed attacks; `highestImpactUncertainty` flags unresolved threats | +| Synthesizer | `observed` aggregates across prior handoffs; `payload` contains integrated conclusions | + +## Open Questions + +1. **Handoff validation**: Who validates that a handoff is "complete enough"? Orchestrator? Successor? Dedicated validator agent? + +2. **Handoff-to-handoff references**: Should handoffs reference prior handoffs by ID? Would enable explicit evidence chains. + +3. **Confidence aggregation**: How do `confidence` scores from `observed` entries propagate when synthesized? + +4. **Failure handoffs**: What does a handoff look like when the step *failed* to complete its intended task? Still valuable for `notDone` and `highestImpactUncertainty`. diff --git a/apps/hash-ai-agent/_ai/plans/PROMPTS-meta-cognitive.md b/apps/hash-ai-agent/_ai/wiki/meta-cognitive-prompts.md similarity index 100% rename from apps/hash-ai-agent/_ai/plans/PROMPTS-meta-cognitive.md rename to apps/hash-ai-agent/_ai/wiki/meta-cognitive-prompts.md From 79b0f4e72f2e22388a38fcf142d86b22e8ce0bd4 Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 22 Dec 2025 12:25:00 +0100 Subject: [PATCH 07/16] unignore the entity-schema fixtures --- apps/hash-ai-agent/.gitignore | 3 - .../entity-schemas/organization.bundled.json | 685 ++++++++++ .../organization.dereferenced.json | 1163 +++++++++++++++++ .../entity-schemas/person.bundled.json | 121 ++ .../entity-schemas/person.dereferenced.json | 139 ++ 5 files changed, 2108 insertions(+), 3 deletions(-) create mode 100644 apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.bundled.json create mode 100644 apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.dereferenced.json create mode 100644 apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/person.bundled.json create mode 100644 apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/person.dereferenced.json diff --git a/apps/hash-ai-agent/.gitignore b/apps/hash-ai-agent/.gitignore index 5b41693247e..774e2ac85e8 100644 --- a/apps/hash-ai-agent/.gitignore +++ b/apps/hash-ai-agent/.gitignore @@ -7,8 +7,5 @@ dist *.db *.db-* -# Fixtures -src/mastra/fixtures/entity-schemas/*.json - # Quokka files *.quokka.* diff --git a/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.bundled.json b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.bundled.json new file mode 100644 index 00000000000..88f4d6b5538 --- /dev/null +++ b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.bundled.json @@ -0,0 +1,685 @@ +{ + "$schema": "https://json-schema.org/draft/2019-09/schema", + "$id": "https://hash.ai/@h/types/entity-type/organization/v/3", + "$defs": { + "blockprotocol_org__blockprotocol_types_data-type_text_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + }, + "blockprotocol_org__blockprotocol_types_property-type_description_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/description/v/1", + "kind": "propertyType", + "title": "Description", + "description": "A piece of text that tells you about something or someone. This can include explaining what they look like, what its purpose is for, what they’re like, etc.", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ] + }, + "blockprotocol_org__blockprotocol_types_property-type_display-name_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/display-name/v/1", + "kind": "propertyType", + "title": "Display Name", + "description": "A human-friendly display name for something", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ] + }, + "blockprotocol_org__blockprotocol_types_property-type_file-hash_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/file-hash/v/1", + "kind": "propertyType", + "title": "File Hash", + "description": "A unique signature derived from a file's contents", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ] + }, + "blockprotocol_org__blockprotocol_types_property-type_file-name_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/file-name/v/1", + "kind": "propertyType", + "title": "File Name", + "description": "The name of a file.", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ] + }, + "blockprotocol_org__blockprotocol_types_data-type_number_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/number/v/1", + "title": "Number", + "description": "An arithmetical value (in the Real number system)", + "type": "number" + }, + "hash_ai__h_types_data-type_information_v_1": { + "$id": "https://hash.ai/@h/types/data-type/information/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": true, + "allOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_number_v_1" + } + ], + "description": "A measure of information content.", + "kind": "dataType", + "title": "Information", + "type": "number" + }, + "hash_ai__h_types_data-type_bytes_v_1": { + "$id": "https://hash.ai/@h/types/data-type/bytes/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_data-type_information_v_1" + } + ], + "description": "A unit of information equal to eight bits.", + "kind": "dataType", + "label": { + "right": "B" + }, + "title": "Bytes", + "type": "number" + }, + "blockprotocol_org__blockprotocol_types_property-type_file-size_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/file-size/v/1", + "kind": "propertyType", + "title": "File Size", + "description": "The size of a file", + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_data-type_bytes_v_1" + } + ] + }, + "hash_ai__h_types_data-type_uri_v_1": { + "$id": "https://hash.ai/@h/types/data-type/uri/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ], + "description": "A unique identifier for a resource (e.g. a URL, or URN).", + "format": "uri", + "kind": "dataType", + "title": "URI", + "type": "string" + }, + "blockprotocol_org__blockprotocol_types_property-type_file-url_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/file-url/v/1", + "kind": "propertyType", + "title": "File URL", + "description": "A URL that serves a file.", + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_data-type_uri_v_1" + } + ] + }, + "blockprotocol_org__blockprotocol_types_property-type_mime-type_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/mime-type/v/1", + "kind": "propertyType", + "title": "MIME Type", + "description": "A MIME (Multipurpose Internet Mail Extensions) type.\n\nSee: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ] + }, + "blockprotocol_org__blockprotocol_types_property-type_original-file-name_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/original-file-name/v/1", + "kind": "propertyType", + "title": "Original File Name", + "description": "The original name of a file", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ] + }, + "blockprotocol_org__blockprotocol_types_property-type_original-source_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/original-source/v/1", + "kind": "propertyType", + "title": "Original Source", + "description": "The original source of something", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ] + }, + "blockprotocol_org__blockprotocol_types_property-type_original-url_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/original-url/v/1", + "kind": "propertyType", + "title": "Original URL", + "description": "The original URL something was hosted at", + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_data-type_uri_v_1" + } + ] + }, + "hash_ai__h_types_property-type_file-storage-bucket_v_1": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-bucket/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The bucket in which a file is stored.", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ], + "title": "File Storage Bucket" + }, + "hash_ai__h_types_property-type_file-storage-endpoint_v_1": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-endpoint/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The endpoint for making requests to a file storage provider.", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ], + "title": "File Storage Endpoint" + }, + "blockprotocol_org__blockprotocol_types_data-type_boolean_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/boolean/v/1", + "title": "Boolean", + "description": "A True or False value", + "type": "boolean" + }, + "hash_ai__h_types_property-type_file-storage-force-path-style_v_1": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-force-path-style/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "Whether to force path style for requests to a file storage provider (vs virtual host style).", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_boolean_v_1" + } + ], + "title": "File Storage Force Path Style" + }, + "hash_ai__h_types_property-type_file-storage-key_v_1": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-key/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The key identifying a file in storage.", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ], + "title": "File Storage Key" + }, + "hash_ai__h_types_property-type_file-storage-provider_v_1": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-provider/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The provider of a file storage service.", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ], + "title": "File Storage Provider" + }, + "hash_ai__h_types_property-type_file-storage-region_v_1": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-region/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The region in which a file is stored.", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ], + "title": "File Storage Region" + }, + "hash_ai__h_types_data-type_datetime_v_1": { + "$id": "https://hash.ai/@h/types/data-type/datetime/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ], + "description": "A reference to a particular date and time, formatted according to RFC 3339.", + "format": "date-time", + "kind": "dataType", + "title": "DateTime", + "type": "string" + }, + "hash_ai__h_types_property-type_upload-completed-at_v_1": { + "$id": "https://hash.ai/@h/types/property-type/upload-completed-at/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The timestamp when the upload of something has completed", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_data-type_datetime_v_1" + } + ], + "title": "Upload Completed At" + }, + "hash_ai__h_types_entity-type_file_v_2": { + "$id": "https://hash.ai/@h/types/entity-type/file/v/2", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "description": "A file hosted at a URL", + "icon": "/icons/types/file.svg", + "kind": "entityType", + "labelProperty": "https://blockprotocol.org/@blockprotocol/types/property-type/display-name/", + "properties": { + "https://blockprotocol.org/@blockprotocol/types/property-type/description/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_description_v_1" + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/display-name/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_display-name_v_1" + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/file-hash/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_file-hash_v_1" + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/file-name/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_file-name_v_1" + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/file-size/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_file-size_v_1" + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/file-url/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_file-url_v_1" + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/mime-type/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_mime-type_v_1" + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/original-file-name/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_original-file-name_v_1" + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/original-source/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_original-source_v_1" + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/original-url/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_original-url_v_1" + }, + "https://hash.ai/@h/types/property-type/file-storage-bucket/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_file-storage-bucket_v_1" + }, + "https://hash.ai/@h/types/property-type/file-storage-endpoint/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_file-storage-endpoint_v_1" + }, + "https://hash.ai/@h/types/property-type/file-storage-force-path-style/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_file-storage-force-path-style_v_1" + }, + "https://hash.ai/@h/types/property-type/file-storage-key/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_file-storage-key_v_1" + }, + "https://hash.ai/@h/types/property-type/file-storage-provider/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_file-storage-provider_v_1" + }, + "https://hash.ai/@h/types/property-type/file-storage-region/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_file-storage-region_v_1" + }, + "https://hash.ai/@h/types/property-type/upload-completed-at/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_upload-completed-at_v_1" + } + }, + "required": [ + "https://blockprotocol.org/@blockprotocol/types/property-type/file-url/" + ], + "title": "File", + "type": "object" + }, + "hash_ai__h_types_entity-type_image-file_v_2": { + "$id": "https://hash.ai/@h/types/entity-type/image-file/v/2", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "allOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_entity-type_file_v_2" + } + ], + "description": "An image file hosted at a URL", + "icon": "/icons/types/file-image.svg", + "kind": "entityType", + "properties": {}, + "title": "Image File", + "type": "object" + }, + "hash_ai__h_types_entity-type_block-collection_v_1": { + "$id": "https://hash.ai/@h/types/entity-type/block-collection/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "description": "A collection of blocks.", + "icon": "/icons/types/cubes.svg", + "kind": "entityType", + "properties": {}, + "title": "Block Collection", + "type": "object" + }, + "hash_ai__h_types_property-type_component-id_v_1": { + "$id": "https://hash.ai/@h/types/property-type/component-id/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "An identifier for a component.", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ], + "title": "Component Id" + }, + "hash_ai__h_types_entity-type_block_v_1": { + "$id": "https://hash.ai/@h/types/entity-type/block/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "description": "A block that displays or otherwise uses data, part of a wider page or collection.", + "icon": "/icons/types/cube.svg", + "kind": "entityType", + "links": { + "https://hash.ai/@h/types/entity-type/has-data/v/1": { + "items": {}, + "maxItems": 1, + "minItems": 1, + "type": "array" + } + }, + "properties": { + "https://hash.ai/@h/types/property-type/component-id/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_component-id_v_1" + } + }, + "required": ["https://hash.ai/@h/types/property-type/component-id/"], + "title": "Block", + "type": "object" + }, + "hash_ai__h_types_entity-type_profile-bio_v_1": { + "$id": "https://hash.ai/@h/types/entity-type/profile-bio/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "allOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_entity-type_block-collection_v_1" + } + ], + "description": "A biography for display on someone or something's profile.", + "icon": "/icons/types/memo-circle-info.svg", + "kind": "entityType", + "links": { + "https://hash.ai/@h/types/entity-type/has-indexed-content/v/1": { + "items": { + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_entity-type_block_v_1" + } + ] + }, + "minItems": 1, + "type": "array" + } + }, + "properties": {}, + "title": "Profile Bio", + "type": "object" + }, + "hash_ai__h_types_property-type_expired-at_v_1": { + "$id": "https://hash.ai/@h/types/property-type/expired-at/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "Stringified timestamp of when something expired.", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_data-type_datetime_v_1" + } + ], + "title": "Expired At" + }, + "hash_ai__h_types_entity-type_invitation_v_1": { + "$id": "https://hash.ai/@h/types/entity-type/invitation/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "description": "A request or offer to join or attend something.", + "kind": "entityType", + "properties": { + "https://hash.ai/@h/types/property-type/expired-at/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_expired-at_v_1" + } + }, + "required": ["https://hash.ai/@h/types/property-type/expired-at/"], + "title": "Invitation", + "type": "object" + }, + "hash_ai__h_types_data-type_email_v_1": { + "$id": "https://hash.ai/@h/types/data-type/email/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ], + "description": "An identifier for an email box to which messages are delivered.", + "format": "email", + "kind": "dataType", + "title": "Email", + "type": "string" + }, + "hash_ai__h_types_property-type_email_v_1": { + "$id": "https://hash.ai/@h/types/property-type/email/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "An email address", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_data-type_email_v_1" + } + ], + "title": "Email" + }, + "hash_ai__h_types_entity-type_invitation-via-email_v_1": { + "$id": "https://hash.ai/@h/types/entity-type/invitation-via-email/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "allOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_entity-type_invitation_v_1" + } + ], + "description": "An invitation issued to an email address.", + "kind": "entityType", + "properties": { + "https://hash.ai/@h/types/property-type/email/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_email_v_1" + } + }, + "required": ["https://hash.ai/@h/types/property-type/email/"], + "title": "Invitation Via Email", + "type": "object" + }, + "hash_ai__h_types_property-type_shortname_v_1": { + "$id": "https://hash.ai/@h/types/property-type/shortname/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "A unique identifier for something, in the form of a slug", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ], + "title": "Shortname" + }, + "hash_ai__h_types_entity-type_invitation-via-shortname_v_1": { + "$id": "https://hash.ai/@h/types/entity-type/invitation-via-shortname/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "allOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_entity-type_invitation_v_1" + } + ], + "description": "An invitation issued to a user via their shortname.", + "kind": "entityType", + "properties": { + "https://hash.ai/@h/types/property-type/shortname/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_shortname_v_1" + } + }, + "required": ["https://hash.ai/@h/types/property-type/shortname/"], + "title": "Invitation Via Shortname", + "type": "object" + }, + "hash_ai__h_types_property-type_location_v_1": { + "$id": "https://hash.ai/@h/types/property-type/location/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "A location for something, expressed as a single string", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ], + "title": "Location" + }, + "hash_ai__h_types_property-type_organization-name_v_1": { + "$id": "https://hash.ai/@h/types/property-type/organization-name/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The name of an organization.", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ], + "title": "Organization Name" + }, + "hash_ai__h_types_property-type_pinned-entity-type-base-url_v_1": { + "$id": "https://hash.ai/@h/types/property-type/pinned-entity-type-base-url/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The base URL of a pinned entity type.", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_data-type_uri_v_1" + } + ], + "title": "Pinned Entity Type Base URL" + }, + "hash_ai__h_types_property-type_website-url_v_1": { + "$id": "https://hash.ai/@h/types/property-type/website-url/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "A URL for a website", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_data-type_uri_v_1" + } + ], + "title": "Website URL" + } + }, + "description": "An organization. Organizations are root-level objects that contain user accounts and teams.", + "icon": "/icons/types/people-group.svg", + "kind": "entityType", + "labelProperty": "https://hash.ai/@h/types/property-type/organization-name/", + "links": { + "https://hash.ai/@h/types/entity-type/has-avatar/v/1": { + "items": { + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_entity-type_image-file_v_2" + } + ] + }, + "maxItems": 1, + "minItems": 0, + "type": "array" + }, + "https://hash.ai/@h/types/entity-type/has-bio/v/1": { + "items": { + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_entity-type_profile-bio_v_1" + } + ] + }, + "maxItems": 1, + "minItems": 0, + "type": "array" + }, + "https://hash.ai/@h/types/entity-type/has-cover-image/v/1": { + "items": { + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_entity-type_image-file_v_2" + } + ] + }, + "maxItems": 1, + "minItems": 0, + "type": "array" + }, + "https://hash.ai/@h/types/entity-type/has-issued-invitation/v/1": { + "items": { + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_entity-type_invitation-via-email_v_1" + }, + { + "$ref": "#/$defs/hash_ai__h_types_entity-type_invitation-via-shortname_v_1" + } + ] + }, + "type": "array" + } + }, + "properties": { + "https://blockprotocol.org/@blockprotocol/types/property-type/description/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_description_v_1" + }, + "https://hash.ai/@h/types/property-type/location/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_location_v_1" + }, + "https://hash.ai/@h/types/property-type/organization-name/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_organization-name_v_1" + }, + "https://hash.ai/@h/types/property-type/pinned-entity-type-base-url/": { + "items": { + "$ref": "#/$defs/hash_ai__h_types_property-type_pinned-entity-type-base-url_v_1" + }, + "maxItems": 5, + "type": "array" + }, + "https://hash.ai/@h/types/property-type/shortname/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_shortname_v_1" + }, + "https://hash.ai/@h/types/property-type/website-url/": { + "$ref": "#/$defs/hash_ai__h_types_property-type_website-url_v_1" + } + }, + "required": [ + "https://hash.ai/@h/types/property-type/shortname/", + "https://hash.ai/@h/types/property-type/organization-name/" + ], + "title": "Organization", + "type": "object" +} diff --git a/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.dereferenced.json b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.dereferenced.json new file mode 100644 index 00000000000..4a3fdc93397 --- /dev/null +++ b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.dereferenced.json @@ -0,0 +1,1163 @@ +{ + "$id": "https://hash.ai/@h/types/entity-type/organization/v/3", + "$schema": "https://json-schema.org/draft/2019-09/schema", + "description": "An organization. Organizations are root-level objects that contain user accounts and teams.", + "icon": "/icons/types/people-group.svg", + "kind": "entityType", + "labelProperty": "https://hash.ai/@h/types/property-type/organization-name/", + "links": { + "https://hash.ai/@h/types/entity-type/has-avatar/v/1": { + "items": { + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/entity-type/image-file/v/2", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "allOf": [ + { + "$id": "https://hash.ai/@h/types/entity-type/file/v/2", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "description": "A file hosted at a URL", + "icon": "/icons/types/file.svg", + "kind": "entityType", + "labelProperty": "https://blockprotocol.org/@blockprotocol/types/property-type/display-name/", + "properties": { + "https://blockprotocol.org/@blockprotocol/types/property-type/description/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/description/v/1", + "kind": "propertyType", + "title": "Description", + "description": "A piece of text that tells you about something or someone. This can include explaining what they look like, what its purpose is for, what they’re like, etc.", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/display-name/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/display-name/v/1", + "kind": "propertyType", + "title": "Display Name", + "description": "A human-friendly display name for something", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/file-hash/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/file-hash/v/1", + "kind": "propertyType", + "title": "File Hash", + "description": "A unique signature derived from a file's contents", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/file-name/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/file-name/v/1", + "kind": "propertyType", + "title": "File Name", + "description": "The name of a file.", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/file-size/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/file-size/v/1", + "kind": "propertyType", + "title": "File Size", + "description": "The size of a file", + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/bytes/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/information/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": true, + "allOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/number/v/1", + "title": "Number", + "description": "An arithmetical value (in the Real number system)", + "type": "number" + } + ], + "description": "A measure of information content.", + "kind": "dataType", + "title": "Information", + "type": "number" + } + ], + "description": "A unit of information equal to eight bits.", + "kind": "dataType", + "label": { + "right": "B" + }, + "title": "Bytes", + "type": "number" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/file-url/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/file-url/v/1", + "kind": "propertyType", + "title": "File URL", + "description": "A URL that serves a file.", + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/uri/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "description": "A unique identifier for a resource (e.g. a URL, or URN).", + "format": "uri", + "kind": "dataType", + "title": "URI", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/mime-type/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/mime-type/v/1", + "kind": "propertyType", + "title": "MIME Type", + "description": "A MIME (Multipurpose Internet Mail Extensions) type.\n\nSee: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/original-file-name/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/original-file-name/v/1", + "kind": "propertyType", + "title": "Original File Name", + "description": "The original name of a file", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/original-source/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/original-source/v/1", + "kind": "propertyType", + "title": "Original Source", + "description": "The original source of something", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/original-url/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/original-url/v/1", + "kind": "propertyType", + "title": "Original URL", + "description": "The original URL something was hosted at", + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/uri/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "description": "A unique identifier for a resource (e.g. a URL, or URN).", + "format": "uri", + "kind": "dataType", + "title": "URI", + "type": "string" + } + ] + }, + "https://hash.ai/@h/types/property-type/file-storage-bucket/": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-bucket/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The bucket in which a file is stored.", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "File Storage Bucket" + }, + "https://hash.ai/@h/types/property-type/file-storage-endpoint/": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-endpoint/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The endpoint for making requests to a file storage provider.", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "File Storage Endpoint" + }, + "https://hash.ai/@h/types/property-type/file-storage-force-path-style/": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-force-path-style/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "Whether to force path style for requests to a file storage provider (vs virtual host style).", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/boolean/v/1", + "title": "Boolean", + "description": "A True or False value", + "type": "boolean" + } + ], + "title": "File Storage Force Path Style" + }, + "https://hash.ai/@h/types/property-type/file-storage-key/": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-key/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The key identifying a file in storage.", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "File Storage Key" + }, + "https://hash.ai/@h/types/property-type/file-storage-provider/": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-provider/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The provider of a file storage service.", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "File Storage Provider" + }, + "https://hash.ai/@h/types/property-type/file-storage-region/": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-region/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The region in which a file is stored.", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "File Storage Region" + }, + "https://hash.ai/@h/types/property-type/upload-completed-at/": { + "$id": "https://hash.ai/@h/types/property-type/upload-completed-at/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The timestamp when the upload of something has completed", + "kind": "propertyType", + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/datetime/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "description": "A reference to a particular date and time, formatted according to RFC 3339.", + "format": "date-time", + "kind": "dataType", + "title": "DateTime", + "type": "string" + } + ], + "title": "Upload Completed At" + } + }, + "required": [ + "https://blockprotocol.org/@blockprotocol/types/property-type/file-url/" + ], + "title": "File", + "type": "object" + } + ], + "description": "An image file hosted at a URL", + "icon": "/icons/types/file-image.svg", + "kind": "entityType", + "properties": {}, + "title": "Image File", + "type": "object" + } + ] + }, + "maxItems": 1, + "minItems": 0, + "type": "array" + }, + "https://hash.ai/@h/types/entity-type/has-bio/v/1": { + "items": { + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/entity-type/profile-bio/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "allOf": [ + { + "$id": "https://hash.ai/@h/types/entity-type/block-collection/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "description": "A collection of blocks.", + "icon": "/icons/types/cubes.svg", + "kind": "entityType", + "properties": {}, + "title": "Block Collection", + "type": "object" + } + ], + "description": "A biography for display on someone or something's profile.", + "icon": "/icons/types/memo-circle-info.svg", + "kind": "entityType", + "links": { + "https://hash.ai/@h/types/entity-type/has-indexed-content/v/1": { + "items": { + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/entity-type/block/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "description": "A block that displays or otherwise uses data, part of a wider page or collection.", + "icon": "/icons/types/cube.svg", + "kind": "entityType", + "links": { + "https://hash.ai/@h/types/entity-type/has-data/v/1": { + "items": {}, + "maxItems": 1, + "minItems": 1, + "type": "array" + } + }, + "properties": { + "https://hash.ai/@h/types/property-type/component-id/": { + "$id": "https://hash.ai/@h/types/property-type/component-id/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "An identifier for a component.", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "Component Id" + } + }, + "required": [ + "https://hash.ai/@h/types/property-type/component-id/" + ], + "title": "Block", + "type": "object" + } + ] + }, + "minItems": 1, + "type": "array" + } + }, + "properties": {}, + "title": "Profile Bio", + "type": "object" + } + ] + }, + "maxItems": 1, + "minItems": 0, + "type": "array" + }, + "https://hash.ai/@h/types/entity-type/has-cover-image/v/1": { + "items": { + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/entity-type/image-file/v/2", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "allOf": [ + { + "$id": "https://hash.ai/@h/types/entity-type/file/v/2", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "description": "A file hosted at a URL", + "icon": "/icons/types/file.svg", + "kind": "entityType", + "labelProperty": "https://blockprotocol.org/@blockprotocol/types/property-type/display-name/", + "properties": { + "https://blockprotocol.org/@blockprotocol/types/property-type/description/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/description/v/1", + "kind": "propertyType", + "title": "Description", + "description": "A piece of text that tells you about something or someone. This can include explaining what they look like, what its purpose is for, what they’re like, etc.", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/display-name/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/display-name/v/1", + "kind": "propertyType", + "title": "Display Name", + "description": "A human-friendly display name for something", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/file-hash/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/file-hash/v/1", + "kind": "propertyType", + "title": "File Hash", + "description": "A unique signature derived from a file's contents", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/file-name/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/file-name/v/1", + "kind": "propertyType", + "title": "File Name", + "description": "The name of a file.", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/file-size/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/file-size/v/1", + "kind": "propertyType", + "title": "File Size", + "description": "The size of a file", + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/bytes/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/information/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": true, + "allOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/number/v/1", + "title": "Number", + "description": "An arithmetical value (in the Real number system)", + "type": "number" + } + ], + "description": "A measure of information content.", + "kind": "dataType", + "title": "Information", + "type": "number" + } + ], + "description": "A unit of information equal to eight bits.", + "kind": "dataType", + "label": { + "right": "B" + }, + "title": "Bytes", + "type": "number" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/file-url/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/file-url/v/1", + "kind": "propertyType", + "title": "File URL", + "description": "A URL that serves a file.", + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/uri/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "description": "A unique identifier for a resource (e.g. a URL, or URN).", + "format": "uri", + "kind": "dataType", + "title": "URI", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/mime-type/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/mime-type/v/1", + "kind": "propertyType", + "title": "MIME Type", + "description": "A MIME (Multipurpose Internet Mail Extensions) type.\n\nSee: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/original-file-name/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/original-file-name/v/1", + "kind": "propertyType", + "title": "Original File Name", + "description": "The original name of a file", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/original-source/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/original-source/v/1", + "kind": "propertyType", + "title": "Original Source", + "description": "The original source of something", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/original-url/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/original-url/v/1", + "kind": "propertyType", + "title": "Original URL", + "description": "The original URL something was hosted at", + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/uri/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "description": "A unique identifier for a resource (e.g. a URL, or URN).", + "format": "uri", + "kind": "dataType", + "title": "URI", + "type": "string" + } + ] + }, + "https://hash.ai/@h/types/property-type/file-storage-bucket/": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-bucket/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The bucket in which a file is stored.", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "File Storage Bucket" + }, + "https://hash.ai/@h/types/property-type/file-storage-endpoint/": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-endpoint/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The endpoint for making requests to a file storage provider.", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "File Storage Endpoint" + }, + "https://hash.ai/@h/types/property-type/file-storage-force-path-style/": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-force-path-style/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "Whether to force path style for requests to a file storage provider (vs virtual host style).", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/boolean/v/1", + "title": "Boolean", + "description": "A True or False value", + "type": "boolean" + } + ], + "title": "File Storage Force Path Style" + }, + "https://hash.ai/@h/types/property-type/file-storage-key/": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-key/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The key identifying a file in storage.", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "File Storage Key" + }, + "https://hash.ai/@h/types/property-type/file-storage-provider/": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-provider/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The provider of a file storage service.", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "File Storage Provider" + }, + "https://hash.ai/@h/types/property-type/file-storage-region/": { + "$id": "https://hash.ai/@h/types/property-type/file-storage-region/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The region in which a file is stored.", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "File Storage Region" + }, + "https://hash.ai/@h/types/property-type/upload-completed-at/": { + "$id": "https://hash.ai/@h/types/property-type/upload-completed-at/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The timestamp when the upload of something has completed", + "kind": "propertyType", + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/datetime/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "description": "A reference to a particular date and time, formatted according to RFC 3339.", + "format": "date-time", + "kind": "dataType", + "title": "DateTime", + "type": "string" + } + ], + "title": "Upload Completed At" + } + }, + "required": [ + "https://blockprotocol.org/@blockprotocol/types/property-type/file-url/" + ], + "title": "File", + "type": "object" + } + ], + "description": "An image file hosted at a URL", + "icon": "/icons/types/file-image.svg", + "kind": "entityType", + "properties": {}, + "title": "Image File", + "type": "object" + } + ] + }, + "maxItems": 1, + "minItems": 0, + "type": "array" + }, + "https://hash.ai/@h/types/entity-type/has-issued-invitation/v/1": { + "items": { + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/entity-type/invitation-via-email/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "allOf": [ + { + "$id": "https://hash.ai/@h/types/entity-type/invitation/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "description": "A request or offer to join or attend something.", + "kind": "entityType", + "properties": { + "https://hash.ai/@h/types/property-type/expired-at/": { + "$id": "https://hash.ai/@h/types/property-type/expired-at/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "Stringified timestamp of when something expired.", + "kind": "propertyType", + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/datetime/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "description": "A reference to a particular date and time, formatted according to RFC 3339.", + "format": "date-time", + "kind": "dataType", + "title": "DateTime", + "type": "string" + } + ], + "title": "Expired At" + } + }, + "required": [ + "https://hash.ai/@h/types/property-type/expired-at/" + ], + "title": "Invitation", + "type": "object" + } + ], + "description": "An invitation issued to an email address.", + "kind": "entityType", + "properties": { + "https://hash.ai/@h/types/property-type/email/": { + "$id": "https://hash.ai/@h/types/property-type/email/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "An email address", + "kind": "propertyType", + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/email/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "description": "An identifier for an email box to which messages are delivered.", + "format": "email", + "kind": "dataType", + "title": "Email", + "type": "string" + } + ], + "title": "Email" + } + }, + "required": ["https://hash.ai/@h/types/property-type/email/"], + "title": "Invitation Via Email", + "type": "object" + }, + { + "$id": "https://hash.ai/@h/types/entity-type/invitation-via-shortname/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "allOf": [ + { + "$id": "https://hash.ai/@h/types/entity-type/invitation/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "description": "A request or offer to join or attend something.", + "kind": "entityType", + "properties": { + "https://hash.ai/@h/types/property-type/expired-at/": { + "$id": "https://hash.ai/@h/types/property-type/expired-at/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "Stringified timestamp of when something expired.", + "kind": "propertyType", + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/datetime/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "description": "A reference to a particular date and time, formatted according to RFC 3339.", + "format": "date-time", + "kind": "dataType", + "title": "DateTime", + "type": "string" + } + ], + "title": "Expired At" + } + }, + "required": [ + "https://hash.ai/@h/types/property-type/expired-at/" + ], + "title": "Invitation", + "type": "object" + } + ], + "description": "An invitation issued to a user via their shortname.", + "kind": "entityType", + "properties": { + "https://hash.ai/@h/types/property-type/shortname/": { + "$id": "https://hash.ai/@h/types/property-type/shortname/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "A unique identifier for something, in the form of a slug", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "Shortname" + } + }, + "required": ["https://hash.ai/@h/types/property-type/shortname/"], + "title": "Invitation Via Shortname", + "type": "object" + } + ] + }, + "type": "array" + } + }, + "properties": { + "https://blockprotocol.org/@blockprotocol/types/property-type/description/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/description/v/1", + "kind": "propertyType", + "title": "Description", + "description": "A piece of text that tells you about something or someone. This can include explaining what they look like, what its purpose is for, what they’re like, etc.", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://hash.ai/@h/types/property-type/location/": { + "$id": "https://hash.ai/@h/types/property-type/location/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "A location for something, expressed as a single string", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "Location" + }, + "https://hash.ai/@h/types/property-type/organization-name/": { + "$id": "https://hash.ai/@h/types/property-type/organization-name/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The name of an organization.", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "Organization Name" + }, + "https://hash.ai/@h/types/property-type/pinned-entity-type-base-url/": { + "items": { + "$id": "https://hash.ai/@h/types/property-type/pinned-entity-type-base-url/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "The base URL of a pinned entity type.", + "kind": "propertyType", + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/uri/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "description": "A unique identifier for a resource (e.g. a URL, or URN).", + "format": "uri", + "kind": "dataType", + "title": "URI", + "type": "string" + } + ], + "title": "Pinned Entity Type Base URL" + }, + "maxItems": 5, + "type": "array" + }, + "https://hash.ai/@h/types/property-type/shortname/": { + "$id": "https://hash.ai/@h/types/property-type/shortname/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "A unique identifier for something, in the form of a slug", + "kind": "propertyType", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "title": "Shortname" + }, + "https://hash.ai/@h/types/property-type/website-url/": { + "$id": "https://hash.ai/@h/types/property-type/website-url/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "A URL for a website", + "kind": "propertyType", + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/uri/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "description": "A unique identifier for a resource (e.g. a URL, or URN).", + "format": "uri", + "kind": "dataType", + "title": "URI", + "type": "string" + } + ], + "title": "Website URL" + } + }, + "required": [ + "https://hash.ai/@h/types/property-type/shortname/", + "https://hash.ai/@h/types/property-type/organization-name/" + ], + "title": "Organization", + "type": "object" +} diff --git a/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/person.bundled.json b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/person.bundled.json new file mode 100644 index 00000000000..786183c7947 --- /dev/null +++ b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/person.bundled.json @@ -0,0 +1,121 @@ +{ + "$schema": "https://json-schema.org/draft/2019-09/schema", + "$id": "https://hash.ai/@h/types/entity-type/person/v/1", + "$defs": { + "blockprotocol_org__blockprotocol_types_data-type_text_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + }, + "blockprotocol_org__blockprotocol_types_property-type_description_v_1": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/description/v/1", + "kind": "propertyType", + "title": "Description", + "description": "A piece of text that tells you about something or someone. This can include explaining what they look like, what its purpose is for, what they’re like, etc.", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ] + }, + "blockprotocol_org__blockprotocol_types_property-type_name_v_1": { + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/name/v/1", + "description": "A word or set of words by which something is known, addressed, or referred to.", + "oneOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ], + "kind": "propertyType", + "title": "Name", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type" + }, + "hash_ai__h_types_entity-type_institution_v_1": { + "$id": "https://hash.ai/@h/types/entity-type/institution/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "description": "An organization dedicated to a specific purpose, such as education, research, or public service, and structured with formal systems of governance and operation.", + "icon": "/icons/types/building-columns.svg", + "kind": "entityType", + "labelProperty": "https://blockprotocol.org/@blockprotocol/types/property-type/name/", + "properties": { + "https://blockprotocol.org/@blockprotocol/types/property-type/description/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_description_v_1" + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/name/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_name_v_1" + } + }, + "required": [ + "https://blockprotocol.org/@blockprotocol/types/property-type/name/" + ], + "title": "Institution", + "type": "object" + }, + "hash_ai__h_types_data-type_email_v_1": { + "$id": "https://hash.ai/@h/types/data-type/email/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_data-type_text_v_1" + } + ], + "description": "An identifier for an email box to which messages are delivered.", + "format": "email", + "kind": "dataType", + "title": "Email", + "type": "string" + }, + "hash_ai__h_types_property-type_email_v_1": { + "$id": "https://hash.ai/@h/types/property-type/email/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "An email address", + "kind": "propertyType", + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_data-type_email_v_1" + } + ], + "title": "Email" + } + }, + "description": "A human being", + "icon": "👤", + "kind": "entityType", + "labelProperty": "https://blockprotocol.org/@blockprotocol/types/property-type/name/", + "links": { + "https://hash.ai/@h/types/entity-type/affiliated-with/v/1": { + "items": { + "oneOf": [ + { + "$ref": "#/$defs/hash_ai__h_types_entity-type_institution_v_1" + } + ] + }, + "type": "array" + } + }, + "properties": { + "https://blockprotocol.org/@blockprotocol/types/property-type/description/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_description_v_1" + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/name/": { + "$ref": "#/$defs/blockprotocol_org__blockprotocol_types_property-type_name_v_1" + }, + "https://hash.ai/@h/types/property-type/email/": { + "items": { + "$ref": "#/$defs/hash_ai__h_types_property-type_email_v_1" + }, + "type": "array" + } + }, + "required": [ + "https://blockprotocol.org/@blockprotocol/types/property-type/name/" + ], + "title": "Person", + "type": "object" +} diff --git a/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/person.dereferenced.json b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/person.dereferenced.json new file mode 100644 index 00000000000..f7a4cdb202f --- /dev/null +++ b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/person.dereferenced.json @@ -0,0 +1,139 @@ +{ + "$id": "https://hash.ai/@h/types/entity-type/person/v/1", + "$schema": "https://json-schema.org/draft/2019-09/schema", + "description": "A human being", + "icon": "👤", + "kind": "entityType", + "labelProperty": "https://blockprotocol.org/@blockprotocol/types/property-type/name/", + "links": { + "https://hash.ai/@h/types/entity-type/affiliated-with/v/1": { + "items": { + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/entity-type/institution/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/entity-type", + "description": "An organization dedicated to a specific purpose, such as education, research, or public service, and structured with formal systems of governance and operation.", + "icon": "/icons/types/building-columns.svg", + "kind": "entityType", + "labelProperty": "https://blockprotocol.org/@blockprotocol/types/property-type/name/", + "properties": { + "https://blockprotocol.org/@blockprotocol/types/property-type/description/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/description/v/1", + "kind": "propertyType", + "title": "Description", + "description": "A piece of text that tells you about something or someone. This can include explaining what they look like, what its purpose is for, what they’re like, etc.", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/name/": { + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/name/v/1", + "description": "A word or set of words by which something is known, addressed, or referred to.", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "kind": "propertyType", + "title": "Name", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type" + } + }, + "required": [ + "https://blockprotocol.org/@blockprotocol/types/property-type/name/" + ], + "title": "Institution", + "type": "object" + } + ] + }, + "type": "array" + } + }, + "properties": { + "https://blockprotocol.org/@blockprotocol/types/property-type/description/": { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/description/v/1", + "kind": "propertyType", + "title": "Description", + "description": "A piece of text that tells you about something or someone. This can include explaining what they look like, what its purpose is for, what they’re like, etc.", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ] + }, + "https://blockprotocol.org/@blockprotocol/types/property-type/name/": { + "$id": "https://blockprotocol.org/@blockprotocol/types/property-type/name/v/1", + "description": "A word or set of words by which something is known, addressed, or referred to.", + "oneOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "kind": "propertyType", + "title": "Name", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type" + }, + "https://hash.ai/@h/types/property-type/email/": { + "items": { + "$id": "https://hash.ai/@h/types/property-type/email/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/property-type", + "description": "An email address", + "kind": "propertyType", + "oneOf": [ + { + "$id": "https://hash.ai/@h/types/data-type/email/v/1", + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "abstract": false, + "allOf": [ + { + "$schema": "https://blockprotocol.org/types/modules/graph/0.3/schema/data-type", + "kind": "dataType", + "$id": "https://blockprotocol.org/@blockprotocol/types/data-type/text/v/1", + "title": "Text", + "description": "An ordered sequence of characters", + "type": "string" + } + ], + "description": "An identifier for an email box to which messages are delivered.", + "format": "email", + "kind": "dataType", + "title": "Email", + "type": "string" + } + ], + "title": "Email" + }, + "type": "array" + } + }, + "required": [ + "https://blockprotocol.org/@blockprotocol/types/property-type/name/" + ], + "title": "Person", + "type": "object" +} From 37c16639d67e6f7b3601c991e64a04600e68ace5 Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 22 Dec 2025 12:29:19 +0100 Subject: [PATCH 08/16] refactor plan-spec to remove silly functions and redundant properties --- .../src/mastra/agents/executor-agents.ts | 193 +++++++++++++++++ .../src/mastra/agents/planner-agent.ts | 7 +- apps/hash-ai-agent/src/mastra/constants.ts | 202 +----------------- .../decomposition-prompts/fixtures.test.ts | 4 +- .../decomposition-prompts/mock-plans.ts | 76 +++---- .../src/mastra/schemas/plan-spec.ts | 106 +++------ .../src/mastra/scorers/ner-people-scorer.ts | 8 +- .../mastra/scorers/plan-llm-scorers.test.ts | 11 +- .../src/mastra/scorers/plan-scorers.test.ts | 36 ++-- .../src/mastra/scorers/plan-scorers.ts | 11 +- .../src/mastra/scripts/demo-plan-execution.ts | 10 +- .../src/mastra/tools/plan-compiler.test.ts | 102 ++++----- .../src/mastra/tools/plan-compiler.ts | 6 +- .../src/mastra/tools/plan-validator.test.ts | 117 +++------- .../src/mastra/tools/plan-validator.ts | 29 ++- .../src/mastra/tools/topology-analyzer.ts | 7 +- .../src/mastra/workflows/revision-feedback.ts | 11 +- 17 files changed, 387 insertions(+), 549 deletions(-) create mode 100644 apps/hash-ai-agent/src/mastra/agents/executor-agents.ts diff --git a/apps/hash-ai-agent/src/mastra/agents/executor-agents.ts b/apps/hash-ai-agent/src/mastra/agents/executor-agents.ts new file mode 100644 index 00000000000..09b4c43e3fc --- /dev/null +++ b/apps/hash-ai-agent/src/mastra/agents/executor-agents.ts @@ -0,0 +1,193 @@ +import type { StepType } from "../schemas/plan-spec"; + +/** + * Capability profile for an available agent. + * + * These profiles help the planner reason about which executor to assign to each step. + * The `canHandle` array maps to PlanSpec step types. + */ + +export interface AgentCapabilityProfile { + /** Human-readable description of what this agent does */ + description: string; + /** Step types this agent can execute */ + canHandle: StepType[]; + /** Named inputs this agent expects */ + inputs: string[]; + /** Named outputs this agent produces */ + outputs: string[]; +} + +/** + * Available agents for plan execution. + * + * Each agent has a capability profile that the planner uses to assign executors. + * The structure supports: + * - Validating that executor refs exist + * - Checking that assigned executors can handle the step type + * - Generating prompt context for the planner + * + * @see docs/PLAN-task-decomposition.md Section 5 for design rationale + */ + +export const AVAILABLE_AGENTS = { + // --------------------------------------------------------------------------- + // Research & Discovery + // --------------------------------------------------------------------------- + "literature-searcher": { + description: "Searches academic papers and technical documentation", + canHandle: ["research"], + inputs: ["query", "sources?"], + outputs: ["papers", "summaries"], + }, + + "paper-summarizer": { + description: "Reads and summarizes academic papers", + canHandle: ["research"], + inputs: ["paper"], + outputs: ["summary", "keyFindings"], + }, + + "concept-explainer": { + description: "Explains technical concepts at varying depths", + canHandle: ["research", "synthesize"], + inputs: ["concept", "targetAudience?"], + outputs: ["explanation"], + }, + + // --------------------------------------------------------------------------- + // Analysis & Synthesis + // --------------------------------------------------------------------------- + "result-synthesizer": { + description: + "Combines findings from multiple sources into coherent understanding", + canHandle: ["synthesize"], + inputs: ["findings[]"], + outputs: ["synthesis", "comparison?"], + }, + + "hypothesis-generator": { + description: "Generates testable hypotheses from findings", + canHandle: ["synthesize"], // integrative mode leading to hypotheses + inputs: ["findings", "constraints"], + outputs: ["hypotheses"], + }, + + "progress-evaluator": { + description: "Assesses current state against goals and criteria", + canHandle: ["synthesize"], // evaluative mode + inputs: ["results", "criteria"], + outputs: ["assessment", "gaps", "recommendations"], + }, + + // --------------------------------------------------------------------------- + // Experimentation + // --------------------------------------------------------------------------- + "experiment-designer": { + description: "Designs experimental procedures with controls", + canHandle: ["experiment"], + inputs: ["hypothesis", "constraints"], + outputs: ["experimentDesign", "protocol"], + }, + + "experiment-runner": { + description: "Executes experiments and collects results", + canHandle: ["experiment"], + inputs: ["experimentDesign", "protocol"], + outputs: ["results", "observations"], + }, + + // --------------------------------------------------------------------------- + // Implementation + // --------------------------------------------------------------------------- + "code-explorer": { + description: "Navigates and explains existing codebases", + canHandle: ["research"], + inputs: ["codebase", "query"], + outputs: ["explanation", "relevantFiles"], + }, + + "code-writer": { + description: "Implements algorithms and prototypes", + canHandle: ["develop", "experiment"], + inputs: ["spec", "context"], + outputs: ["code", "tests?"], + }, + + "code-reviewer": { + description: "Reviews code for correctness and quality", + canHandle: ["synthesize"], // evaluative mode + inputs: ["code", "criteria"], + outputs: ["review", "issues"], + }, + + "documentation-writer": { + description: "Writes technical documentation", + canHandle: ["develop"], + inputs: ["code", "context"], + outputs: ["documentation"], + }, +} as const satisfies Record; +/** + * Type for available agent identifiers. + */ + +export type AgentRef = keyof typeof AVAILABLE_AGENTS; +/** + * Get the capability profile for an agent. + */ + +export function getAgentProfile(ref: AgentRef): AgentCapabilityProfile { + return AVAILABLE_AGENTS[ref]; +} +/** + * Check if an agent can handle a given step type. + */ + +export function canAgentHandle(ref: AgentRef, stepType: StepType): boolean { + const profile = AVAILABLE_AGENTS[ref]; + // Cast needed because canHandle is a readonly tuple from `as const` + return (profile.canHandle as readonly StepType[]).includes(stepType); +} +/** + * Get all agents that can handle a given step type. + */ + +export function getAgentsForStepType(stepType: StepType): AgentRef[] { + return (Object.keys(AVAILABLE_AGENTS) as AgentRef[]).filter((ref) => + canAgentHandle(ref, stepType), + ); +} +/** + * Format available agents for inclusion in planner prompts. + * + * Groups agents by the step types they can handle for easier reasoning. + */ + +export function formatAgentsForPrompt(): string { + const byStepType: Record = { + research: [], + synthesize: [], + experiment: [], + develop: [], + }; + + for (const [ref, profile] of Object.entries(AVAILABLE_AGENTS)) { + for (const stepType of profile.canHandle) { + const inputsStr = profile.inputs.join(", "); + const outputsStr = profile.outputs.join(", "); + byStepType[stepType].push( + ` - ${ref}: ${profile.description}. Inputs: [${inputsStr}]. Outputs: [${outputsStr}].`, + ); + } + } + + const sections: string[] = []; + for (const [stepType, agents] of Object.entries(byStepType)) { + if (agents.length > 0) { + sections.push(`${stepType.toUpperCase()}:\n${agents.join("\n")}`); + } + } + + return `Available executors for your plan:\n\n${sections.join("\n\n")}`; +} diff --git a/apps/hash-ai-agent/src/mastra/agents/planner-agent.ts b/apps/hash-ai-agent/src/mastra/agents/planner-agent.ts index 875d294be3a..76eaa1e1db1 100644 --- a/apps/hash-ai-agent/src/mastra/agents/planner-agent.ts +++ b/apps/hash-ai-agent/src/mastra/agents/planner-agent.ts @@ -12,9 +12,10 @@ import { Agent } from "@mastra/core/agent"; import dedent from "dedent"; -import { DEFAULT_MODEL, formatAgentsForPrompt } from "../constants"; +import { DEFAULT_MODEL } from "../constants"; import type { PlanSpec } from "../schemas/plan-spec"; import { zPlanSpec } from "../schemas/plan-spec"; +import { formatAgentsForPrompt } from "./executor-agents"; /** * System instructions for the planner agent. @@ -123,7 +124,7 @@ Structure your uncertainties into four categories (all are required): ## Output Requirements - Generate unique IDs for requirements (R1, R2...), hypotheses (H1, H2...), and steps (S1, S2...) - - Ensure dependsOn references only existing step IDs + - Ensure dependencyIds references only existing step IDs - Ensure hypothesisIds references only existing hypothesis IDs - Ensure requirementIds references only existing requirement IDs - Create a valid DAG (no circular dependencies) @@ -202,7 +203,7 @@ export async function generatePlan( Decompose this goal into a structured plan. Ensure: - All step dependencies form a valid DAG (no cycles) - - All references (hypothesisIds, requirementIds, dependsOn) point to existing IDs + - All references (hypothesisIds, requirementIds, dependencyIds) point to existing IDs - Each step has an appropriate executor assigned - The unknowns map captures your uncertainty honestly diff --git a/apps/hash-ai-agent/src/mastra/constants.ts b/apps/hash-ai-agent/src/mastra/constants.ts index 7b796e9d447..82645fd9915 100644 --- a/apps/hash-ai-agent/src/mastra/constants.ts +++ b/apps/hash-ai-agent/src/mastra/constants.ts @@ -6,8 +6,6 @@ import type { ModelForProvider } from "@mastra/core/llm/model"; -import type { StepType } from "./schemas/plan-spec"; - export type OpenRouterModelId = `openrouter/${ModelForProvider<"openrouter">}`; /** @@ -24,203 +22,5 @@ export const DEFAULT_MODEL = * Used as the canonical key for extracting/matching person and organization names * in structured entity output. */ -export const NAME_PROPERTY = +export const NAME_PROPERTY_SCHEMA = "https://blockprotocol.org/@blockprotocol/types/property-type/name/"; - -// ============================================================================= -// AVAILABLE AGENTS (for Task Decomposition Planning) -// ============================================================================= - -/** - * Capability profile for an available agent. - * - * These profiles help the planner reason about which executor to assign to each step. - * The `canHandle` array maps to PlanSpec step types. - */ -export interface AgentCapabilityProfile { - /** Human-readable description of what this agent does */ - description: string; - /** Step types this agent can execute */ - canHandle: StepType[]; - /** Named inputs this agent expects */ - inputs: string[]; - /** Named outputs this agent produces */ - outputs: string[]; -} - -/** - * Available agents for plan execution. - * - * Each agent has a capability profile that the planner uses to assign executors. - * The structure supports: - * - Validating that executor refs exist - * - Checking that assigned executors can handle the step type - * - Generating prompt context for the planner - * - * @see docs/PLAN-task-decomposition.md Section 5 for design rationale - */ -export const AVAILABLE_AGENTS = { - // --------------------------------------------------------------------------- - // Research & Discovery - // --------------------------------------------------------------------------- - - "literature-searcher": { - description: "Searches academic papers and technical documentation", - canHandle: ["research"], - inputs: ["query", "sources?"], - outputs: ["papers", "summaries"], - }, - - "paper-summarizer": { - description: "Reads and summarizes academic papers", - canHandle: ["research"], - inputs: ["paper"], - outputs: ["summary", "keyFindings"], - }, - - "concept-explainer": { - description: "Explains technical concepts at varying depths", - canHandle: ["research", "synthesize"], - inputs: ["concept", "targetAudience?"], - outputs: ["explanation"], - }, - - // --------------------------------------------------------------------------- - // Analysis & Synthesis - // --------------------------------------------------------------------------- - - "result-synthesizer": { - description: - "Combines findings from multiple sources into coherent understanding", - canHandle: ["synthesize"], - inputs: ["findings[]"], - outputs: ["synthesis", "comparison?"], - }, - - "hypothesis-generator": { - description: "Generates testable hypotheses from findings", - canHandle: ["synthesize"], // integrative mode leading to hypotheses - inputs: ["findings", "constraints"], - outputs: ["hypotheses"], - }, - - "progress-evaluator": { - description: "Assesses current state against goals and criteria", - canHandle: ["synthesize"], // evaluative mode - inputs: ["results", "criteria"], - outputs: ["assessment", "gaps", "recommendations"], - }, - - // --------------------------------------------------------------------------- - // Experimentation - // --------------------------------------------------------------------------- - - "experiment-designer": { - description: "Designs experimental procedures with controls", - canHandle: ["experiment"], - inputs: ["hypothesis", "constraints"], - outputs: ["experimentDesign", "protocol"], - }, - - "experiment-runner": { - description: "Executes experiments and collects results", - canHandle: ["experiment"], - inputs: ["experimentDesign", "protocol"], - outputs: ["results", "observations"], - }, - - // --------------------------------------------------------------------------- - // Implementation - // --------------------------------------------------------------------------- - - "code-explorer": { - description: "Navigates and explains existing codebases", - canHandle: ["research"], - inputs: ["codebase", "query"], - outputs: ["explanation", "relevantFiles"], - }, - - "code-writer": { - description: "Implements algorithms and prototypes", - canHandle: ["develop", "experiment"], - inputs: ["spec", "context"], - outputs: ["code", "tests?"], - }, - - "code-reviewer": { - description: "Reviews code for correctness and quality", - canHandle: ["synthesize"], // evaluative mode - inputs: ["code", "criteria"], - outputs: ["review", "issues"], - }, - - "documentation-writer": { - description: "Writes technical documentation", - canHandle: ["develop"], - inputs: ["code", "context"], - outputs: ["documentation"], - }, -} as const satisfies Record; - -/** - * Type for available agent identifiers. - */ -export type AgentRef = keyof typeof AVAILABLE_AGENTS; - -/** - * Get the capability profile for an agent. - */ -export function getAgentProfile(ref: AgentRef): AgentCapabilityProfile { - return AVAILABLE_AGENTS[ref]; -} - -/** - * Check if an agent can handle a given step type. - */ -export function canAgentHandle(ref: AgentRef, stepType: StepType): boolean { - const profile = AVAILABLE_AGENTS[ref]; - // Cast needed because canHandle is a readonly tuple from `as const` - return (profile.canHandle as readonly StepType[]).includes(stepType); -} - -/** - * Get all agents that can handle a given step type. - */ -export function getAgentsForStepType(stepType: StepType): AgentRef[] { - return (Object.keys(AVAILABLE_AGENTS) as AgentRef[]).filter((ref) => - canAgentHandle(ref, stepType), - ); -} - -/** - * Format available agents for inclusion in planner prompts. - * - * Groups agents by the step types they can handle for easier reasoning. - */ -export function formatAgentsForPrompt(): string { - const byStepType: Record = { - research: [], - synthesize: [], - experiment: [], - develop: [], - }; - - for (const [ref, profile] of Object.entries(AVAILABLE_AGENTS)) { - for (const stepType of profile.canHandle) { - const inputsStr = profile.inputs.join(", "); - const outputsStr = profile.outputs.join(", "); - byStepType[stepType].push( - ` - ${ref}: ${profile.description}. Inputs: [${inputsStr}]. Outputs: [${outputsStr}].`, - ); - } - } - - const sections: string[] = []; - for (const [stepType, agents] of Object.entries(byStepType)) { - if (agents.length > 0) { - sections.push(`${stepType.toUpperCase()}:\n${agents.join("\n")}`); - } - } - - return `Available executors for your plan:\n\n${sections.join("\n\n")}`; -} diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts index 0786b5bb3c5..066acd333e1 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts +++ b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts @@ -59,7 +59,9 @@ async function runFixtureTest(fixture: PlanningFixture): Promise { console.log(`\nSteps:`); for (const step of plan.steps) { const deps = - step.dependsOn.length > 0 ? ` (deps: ${step.dependsOn.join(", ")})` : ""; + step.dependencyIds.length > 0 + ? ` (deps: ${step.dependencyIds.join(", ")})` + : ""; console.log( ` ${step.id}: [${step.type}] ${step.description.slice(0, 50)}...${deps}`, ); diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts index 5e8867c186d..3ed3c1726f2 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts +++ b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts @@ -49,7 +49,7 @@ export const mockSummarizePapersPlan: PlanSpec = { type: "research", id: "S1", description: "Search for recent RAG papers focusing on architecture", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [ @@ -66,7 +66,7 @@ export const mockSummarizePapersPlan: PlanSpec = { type: "research", id: "S2", description: "Search for RAG papers focusing on retrieval methods", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [ @@ -81,7 +81,7 @@ export const mockSummarizePapersPlan: PlanSpec = { type: "research", id: "S3", description: "Search for RAG papers with performance benchmarks", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [ @@ -96,12 +96,12 @@ export const mockSummarizePapersPlan: PlanSpec = { type: "synthesize", id: "S4", description: "Create comparison table from all three papers", - dependsOn: ["S1", "S2", "S3"], + dependencyIds: ["S1", "S2", "S3"], requirementIds: ["R2", "R3"], inputs: [ - { name: "paper_1", description: "First paper", fromStepId: "S1" }, - { name: "paper_2", description: "Second paper", fromStepId: "S2" }, - { name: "paper_3", description: "Third paper", fromStepId: "S3" }, + { name: "paper_1", description: "First paper" }, + { name: "paper_2", description: "Second paper" }, + { name: "paper_3", description: "Third paper" }, ], outputs: [ { @@ -110,7 +110,6 @@ export const mockSummarizePapersPlan: PlanSpec = { }, ], mode: "integrative", - inputStepIds: ["S1", "S2", "S3"], parallelizable: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, @@ -184,7 +183,7 @@ export const mockExploreAndRecommendPlan: PlanSpec = { type: "research", id: "S1", description: "Deep dive into HNSW indexing", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [ @@ -204,7 +203,7 @@ export const mockExploreAndRecommendPlan: PlanSpec = { type: "research", id: "S2", description: "Deep dive into IVF indexing", - dependsOn: [], + dependencyIds: [], requirementIds: ["R2"], inputs: [], outputs: [ @@ -224,7 +223,7 @@ export const mockExploreAndRecommendPlan: PlanSpec = { type: "research", id: "S3", description: "Research hybrid and emerging approaches", - dependsOn: [], + dependencyIds: [], requirementIds: ["R3"], inputs: [], outputs: [ @@ -242,19 +241,17 @@ export const mockExploreAndRecommendPlan: PlanSpec = { type: "synthesize", id: "S4", description: "Compare all approaches against our requirements", - dependsOn: ["S1", "S2", "S3"], + dependencyIds: ["S1", "S2", "S3"], requirementIds: ["R4"], inputs: [ { name: "hnsw_analysis", description: "HNSW research", - fromStepId: "S1", }, - { name: "ivf_analysis", description: "IVF research", fromStepId: "S2" }, + { name: "ivf_analysis", description: "IVF research" }, { name: "other_approaches", description: "Other approaches", - fromStepId: "S3", }, ], outputs: [ @@ -265,7 +262,6 @@ export const mockExploreAndRecommendPlan: PlanSpec = { }, ], mode: "integrative", - inputStepIds: ["S1", "S2", "S3"], parallelizable: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, @@ -273,13 +269,12 @@ export const mockExploreAndRecommendPlan: PlanSpec = { type: "synthesize", id: "S5", description: "Evaluate options and make recommendation", - dependsOn: ["S4"], + dependencyIds: ["S4"], requirementIds: ["R5"], inputs: [ { name: "comparison_matrix", description: "Comparison results", - fromStepId: "S4", }, ], outputs: [ @@ -289,7 +284,6 @@ export const mockExploreAndRecommendPlan: PlanSpec = { }, ], mode: "evaluative", - inputStepIds: ["S4"], evaluateAgainst: [ "Query latency <100ms at 10M scale", "Memory efficiency for production deployment", @@ -396,7 +390,7 @@ export const mockHypothesisValidationPlan: PlanSpec = { type: "research", id: "S1", description: "Review prior work on fine-tuning vs few-shot for NER", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [ @@ -416,13 +410,12 @@ export const mockHypothesisValidationPlan: PlanSpec = { type: "experiment", id: "S2", description: "Establish few-shot GPT-4 baseline", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], inputs: [ { name: "prior_work", description: "Inform prompt design", - fromStepId: "S1", }, ], outputs: [ @@ -450,13 +443,12 @@ export const mockHypothesisValidationPlan: PlanSpec = { type: "develop", id: "S3", description: "Fine-tune Llama 3 8B on training data", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R2"], inputs: [ { name: "prior_work", description: "Inform fine-tuning approach", - fromStepId: "S1", }, ], outputs: [ @@ -479,13 +471,12 @@ export const mockHypothesisValidationPlan: PlanSpec = { type: "experiment", id: "S4", description: "Evaluate fine-tuned model on test set", - dependsOn: ["S3"], + dependencyIds: ["S3"], requirementIds: ["R3"], inputs: [ { name: "fine_tuned_model", description: "Trained model", - fromStepId: "S3", }, ], outputs: [ @@ -518,18 +509,16 @@ export const mockHypothesisValidationPlan: PlanSpec = { type: "synthesize", id: "S5", description: "Analyze results and make recommendation", - dependsOn: ["S2", "S4"], + dependencyIds: ["S2", "S4"], requirementIds: ["R4", "R5"], inputs: [ { name: "baseline_results", description: "GPT-4 baseline", - fromStepId: "S2", }, { name: "finetuned_results", description: "Fine-tuned results", - fromStepId: "S4", }, ], outputs: [ @@ -539,7 +528,6 @@ export const mockHypothesisValidationPlan: PlanSpec = { }, ], mode: "evaluative", - inputStepIds: ["S2", "S4"], evaluateAgainst: [ "F1 score comparison (primary metric)", "Inference cost at 10K docs/day", @@ -660,7 +648,7 @@ export const mockCtDatabasePlan: PlanSpec = { type: "research", id: "S1", description: "Survey CT foundations in database theory", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [ @@ -679,7 +667,7 @@ export const mockCtDatabasePlan: PlanSpec = { type: "research", id: "S2", description: "Survey CT in programming languages", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [ @@ -696,7 +684,7 @@ export const mockCtDatabasePlan: PlanSpec = { id: "S3", description: "Analyze existing CT-based systems (CQL, Algebraic Databases)", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [ @@ -716,23 +704,20 @@ export const mockCtDatabasePlan: PlanSpec = { type: "synthesize", id: "S4", description: "Synthesize research into design principles", - dependsOn: ["S1", "S2", "S3"], + dependencyIds: ["S1", "S2", "S3"], requirementIds: ["R1"], inputs: [ { name: "db_theory_survey", description: "DB theory", - fromStepId: "S1", }, { name: "pl_theory_survey", description: "PL theory", - fromStepId: "S2", }, { name: "existing_systems", description: "Existing systems", - fromStepId: "S3", }, ], outputs: [ @@ -742,7 +727,6 @@ export const mockCtDatabasePlan: PlanSpec = { }, ], mode: "integrative", - inputStepIds: ["S1", "S2", "S3"], parallelizable: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, @@ -750,13 +734,12 @@ export const mockCtDatabasePlan: PlanSpec = { type: "experiment", id: "S5", description: "Feasibility: Implement and index basic CT structures", - dependsOn: ["S4"], + dependencyIds: ["S4"], requirementIds: ["R2"], inputs: [ { name: "design_principles", description: "Design guidance", - fromStepId: "S4", }, ], outputs: [ @@ -784,13 +767,12 @@ export const mockCtDatabasePlan: PlanSpec = { type: "experiment", id: "S6", description: "Performance: Benchmark against PostgreSQL", - dependsOn: ["S5"], + dependencyIds: ["S5"], requirementIds: ["R3"], inputs: [ { name: "feasibility_results", description: "Feasibility results", - fromStepId: "S5", }, ], outputs: [ @@ -820,20 +802,18 @@ export const mockCtDatabasePlan: PlanSpec = { type: "synthesize", id: "S7", description: "Go/no-go decision on prototype development", - dependsOn: ["S6"], + dependencyIds: ["S6"], requirementIds: ["R4"], inputs: [ { name: "benchmark_results", description: "Benchmark results", - fromStepId: "S6", }, ], outputs: [ { name: "go_decision", description: "Decision and justification" }, ], mode: "evaluative", - inputStepIds: ["S6"], evaluateAgainst: [ "Performance within 2x of traditional DB", "Clear path to optimization", @@ -846,11 +826,9 @@ export const mockCtDatabasePlan: PlanSpec = { type: "develop", id: "S8", description: "Develop prototype with functor-based migrations", - dependsOn: ["S7"], + dependencyIds: ["S7"], requirementIds: ["R4", "R5"], - inputs: [ - { name: "go_decision", description: "Go decision", fromStepId: "S7" }, - ], + inputs: [{ name: "go_decision", description: "Go decision" }], outputs: [ { name: "prototype", diff --git a/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts b/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts index 1643835bc98..818c5249c77 100644 --- a/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts +++ b/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts @@ -34,6 +34,15 @@ import { z } from "zod"; export const zAimType = z.enum(["describe", "explain", "predict", "intervene"]); export type AimType = z.infer; +export const STEP_TYPES = [ + "research", + "synthesize", + "experiment", + "develop", +] as const; +export const zStepType = z.enum(STEP_TYPES); +export type StepType = z.infer; + // ============================================================================= // REQUIREMENTS // ============================================================================= @@ -88,6 +97,7 @@ export const zHypothesis = z.object({ .describe("How this hypothesis can be tested (what experiment/evidence)"), status: zHypothesisStatus.default("untested"), }); + export type Hypothesis = z.infer; // ============================================================================= @@ -106,6 +116,7 @@ export const zUnknownUnknown = z.object({ .string() .describe("How would we notice? What would be the signal?"), }); + export type UnknownUnknown = z.infer; /** @@ -135,6 +146,7 @@ export const zUnknownsMap = z.object({ .string() .describe("What others would need to see to scrutinize our claims"), }); + export type UnknownsMap = z.infer; // ============================================================================= @@ -150,11 +162,8 @@ export type UnknownsMap = z.infer; export const zDataContract = z.object({ name: z.string().describe("Name of the data artifact"), description: z.string().describe("What this data represents"), - fromStepId: z - .string() - .optional() - .describe("Step that produces this (for inputs)"), }); + export type DataContract = z.infer; // ============================================================================= @@ -171,6 +180,7 @@ export const zEvalCriteria = z.object({ .optional() .describe("What constitutes failure (if different from !success)"), }); + export type EvalCriteria = z.infer; // ============================================================================= @@ -207,6 +217,7 @@ export const zExecutor = z.discriminatedUnion("kind", [ .describe("Instructions for human executor"), }), ]); + export type Executor = z.infer; // ============================================================================= @@ -217,9 +228,10 @@ export type Executor = z.infer; * Common fields shared by all step types. */ export const zBaseStep = z.object({ + type: zStepType, id: z.string().describe("Unique identifier (e.g., 'S1', 'S2')"), description: z.string().describe("What this step accomplishes"), - dependsOn: z + dependencyIds: z .array(z.string()) .describe("Step IDs that must complete before this step"), requirementIds: z @@ -249,7 +261,7 @@ export const zBaseStep = z.object({ * defining what "done" means. */ export const zResearchStep = zBaseStep.extend({ - type: z.literal("research"), + type: zStepType.extract(["research"]), query: z.string().describe("The research question or search query"), stoppingRule: z .string() @@ -267,15 +279,6 @@ export type ResearchStep = z.infer; // Synthesize Step // ----------------------------------------------------------------------------- -/** - * Synthesis modes. - * - * - integrative: Combine findings from multiple sources into coherent understanding - * - evaluative: Judge results against criteria (subsumes old "assess" step type) - */ -export const zSynthesisMode = z.enum(["integrative", "evaluative"]); -export type SynthesisMode = z.infer; - /** * A synthesize step for combining or evaluating results. * @@ -285,11 +288,10 @@ export type SynthesisMode = z.infer; * Evaluative synthesis judges results against specific criteria. */ export const zSynthesizeStep = zBaseStep.extend({ - type: z.literal("synthesize"), - mode: zSynthesisMode.describe("integrative (combine) or evaluative (judge)"), - inputStepIds: z - .array(z.string()) - .describe("Step IDs whose outputs to synthesize"), + type: zStepType.extract(["synthesize"]), + mode: z + .enum(["integrative", "evaluative"]) + .describe("integrative (combine) or evaluative (judge)"), evaluateAgainst: z .array(z.string()) .optional() @@ -328,7 +330,7 @@ export type ExperimentMode = z.infer; * locked before seeing outcomes. This is validated by the experiment-rigor scorer. */ export const zExperimentStep = zBaseStep.extend({ - type: z.literal("experiment"), + type: zStepType.extract(["experiment"]), mode: zExperimentMode.describe("exploratory or confirmatory"), hypothesisIds: z.array(z.string()).describe("Hypothesis IDs being tested"), procedure: z.string().describe("How the experiment will be conducted"), @@ -361,7 +363,7 @@ export type ExperimentStep = z.infer; * Develop steps may or may not be parallelizable depending on dependencies. */ export const zDevelopStep = zBaseStep.extend({ - type: z.literal("develop"), + type: zStepType.extract(["develop"]), specification: z.string().describe("What to build/implement"), deliverables: z.array(z.string()).describe("Concrete outputs to produce"), parallelizable: z @@ -386,17 +388,6 @@ export const zPlanStep = z.discriminatedUnion("type", [ ]); export type PlanStep = z.infer; -/** - * Step type literals for type-safe checks. - */ -export const STEP_TYPES = [ - "research", - "synthesize", - "experiment", - "develop", -] as const; -export type StepType = (typeof STEP_TYPES)[number]; - // ============================================================================= // PLAN SPEC (Full IR) // ============================================================================= @@ -450,52 +441,3 @@ export const zPlanSpec = z.object({ .describe("Estimated complexity of the plan"), }); export type PlanSpec = z.infer; - -// ============================================================================= -// VALIDATION HELPERS -// ============================================================================= - -/** - * Check if a step is parallelizable based on its type and configuration. - */ -export function isParallelizable(step: PlanStep): boolean { - return step.parallelizable; -} - -/** - * Get all step IDs referenced by a step (dependencies + inputs). - */ -export function getStepReferences(step: PlanStep): string[] { - const refs = [...step.dependsOn]; - - // Add inputStepIds for synthesize steps - if (step.type === "synthesize") { - refs.push(...step.inputStepIds); - } - - // Add fromStepId from inputs - for (const input of step.inputs) { - if (input.fromStepId) { - refs.push(input.fromStepId); - } - } - - return Array.from(new Set(refs)); // Deduplicate -} - -/** - * Get all hypothesis IDs referenced by a step. - */ -export function getHypothesisReferences(step: PlanStep): string[] { - if (step.type === "experiment") { - return step.hypothesisIds; - } - return []; -} - -/** - * Get all requirement IDs referenced by a step. - */ -export function getRequirementReferences(step: PlanStep): string[] { - return step.requirementIds; -} diff --git a/apps/hash-ai-agent/src/mastra/scorers/ner-people-scorer.ts b/apps/hash-ai-agent/src/mastra/scorers/ner-people-scorer.ts index 80d3621ad3c..556a51fb6ad 100644 --- a/apps/hash-ai-agent/src/mastra/scorers/ner-people-scorer.ts +++ b/apps/hash-ai-agent/src/mastra/scorers/ner-people-scorer.ts @@ -1,12 +1,12 @@ import { createScorer } from "@mastra/core/evals"; import { z } from "zod"; -import { DEFAULT_MODEL, NAME_PROPERTY } from "../constants"; +import { DEFAULT_MODEL, NAME_PROPERTY_SCHEMA } from "../constants"; /** Schema for extracted person entity */ const zPersonEntity = z .object({ - [NAME_PROPERTY]: z.string(), + [NAME_PROPERTY_SCHEMA]: z.string(), }) .passthrough(); // allow other properties like description @@ -66,7 +66,7 @@ Be precise: only match names that clearly refer to the same real-world person.`, } else { for (const person of output) { const personObj = person as Record; - const name = personObj[NAME_PROPERTY]; + const name = personObj[NAME_PROPERTY_SCHEMA]; if (typeof name === "string") { extractedNames.push(name); } @@ -76,7 +76,7 @@ Be precise: only match names that clearly refer to the same real-world person.`, // Parse ground truth const groundTruth = zGroundTruth.parse(run.groundTruth); const expectedNames = groundTruth.expectedPersons.map( - (person) => person[NAME_PROPERTY], + (person) => person[NAME_PROPERTY_SCHEMA], ); return { extractedNames, expectedNames }; diff --git a/apps/hash-ai-agent/src/mastra/scorers/plan-llm-scorers.test.ts b/apps/hash-ai-agent/src/mastra/scorers/plan-llm-scorers.test.ts index e6c62f3567e..adab6b13e65 100644 --- a/apps/hash-ai-agent/src/mastra/scorers/plan-llm-scorers.test.ts +++ b/apps/hash-ai-agent/src/mastra/scorers/plan-llm-scorers.test.ts @@ -48,7 +48,7 @@ function createMinimalTestPlan(): PlanSpec { type: "research", id: "S1", description: "Search for recent papers on RAG", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "papers", description: "Found papers" }], @@ -61,12 +61,11 @@ function createMinimalTestPlan(): PlanSpec { type: "synthesize", id: "S2", description: "Create comparison table from papers", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1", "R2"], - inputs: [{ name: "papers", description: "Papers", fromStepId: "S1" }], + inputs: [{ name: "papers", description: "Papers" }], outputs: [{ name: "comparison", description: "Comparison table" }], mode: "integrative", - inputStepIds: ["S1"], parallelizable: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, @@ -127,7 +126,7 @@ function createPlanWithHypotheses(): PlanSpec { type: "research", id: "S1", description: "Review fine-tuning best practices", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "practices", description: "Best practices" }], @@ -140,7 +139,7 @@ function createPlanWithHypotheses(): PlanSpec { type: "experiment", id: "S2", description: "Run comparison experiment", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], inputs: [], outputs: [{ name: "results", description: "Experiment results" }], diff --git a/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.test.ts b/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.test.ts index 526d22da923..b954223ee91 100644 --- a/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.test.ts +++ b/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.test.ts @@ -36,7 +36,7 @@ function createMinimalPlan(): PlanSpec { type: "research", id: "S1", description: "Research", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "findings", description: "Findings" }], @@ -94,7 +94,7 @@ function createComplexPlan(): PlanSpec { type: "research", id: "S1", description: "Initial research", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "findings", description: "Findings" }], @@ -107,7 +107,7 @@ function createComplexPlan(): PlanSpec { type: "research", id: "S2", description: "Parallel research", - dependsOn: [], + dependencyIds: [], requirementIds: ["R2"], inputs: [], outputs: [{ name: "data", description: "Data" }], @@ -120,15 +120,14 @@ function createComplexPlan(): PlanSpec { type: "synthesize", id: "S3", description: "Combine findings", - dependsOn: ["S1", "S2"], + dependencyIds: ["S1", "S2"], requirementIds: ["R1", "R2"], inputs: [ - { name: "findings", description: "From S1", fromStepId: "S1" }, - { name: "data", description: "From S2", fromStepId: "S2" }, + { name: "findings", description: "From S1" }, + { name: "data", description: "From S2" }, ], outputs: [{ name: "synthesis", description: "Combined understanding" }], mode: "integrative", - inputStepIds: ["S1", "S2"], parallelizable: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, @@ -136,11 +135,9 @@ function createComplexPlan(): PlanSpec { type: "experiment", id: "S4", description: "Test hypothesis", - dependsOn: ["S3"], + dependencyIds: ["S3"], requirementIds: ["R1"], - inputs: [ - { name: "synthesis", description: "From S3", fromStepId: "S3" }, - ], + inputs: [{ name: "synthesis", description: "From S3" }], outputs: [{ name: "results", description: "Experiment results" }], mode: "confirmatory", hypothesisIds: ["H1"], @@ -155,9 +152,9 @@ function createComplexPlan(): PlanSpec { type: "develop", id: "S5", description: "Build prototype", - dependsOn: ["S4"], + dependencyIds: ["S4"], requirementIds: ["R3"], - inputs: [{ name: "results", description: "From S4", fromStepId: "S4" }], + inputs: [{ name: "results", description: "From S4" }], outputs: [{ name: "prototype", description: "Working prototype" }], specification: "Build X based on findings", deliverables: ["Code", "Tests"], @@ -201,7 +198,7 @@ describe("scorePlanStructure", () => { test("returns zero score for invalid DAG", () => { const plan = createMinimalPlan(); - plan.steps[0]!.dependsOn = ["S1"]; // Self-cycle + plan.steps[0]!.dependencyIds = ["S1"]; // Self-cycle const result = scorePlanStructure(plan); @@ -216,12 +213,11 @@ describe("scorePlanStructure", () => { type: "synthesize", id: "S2", description: "Synthesize", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], inputs: [], outputs: [], mode: "integrative", - inputStepIds: ["S1"], parallelizable: false, executor: { kind: "agent", ref: "result-synthesizer" }, }); @@ -231,7 +227,7 @@ describe("scorePlanStructure", () => { type: "research", id: "S2", description: "Parallel research", - dependsOn: [], // No dependency — can run in parallel + dependencyIds: [], // No dependency — can run in parallel requirementIds: ["R1"], inputs: [], outputs: [], @@ -377,7 +373,7 @@ describe("scoreExperimentRigor", () => { type: "experiment", id: "S2", description: "Experiment", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], inputs: [], outputs: [], @@ -412,7 +408,7 @@ describe("scoreExperimentRigor", () => { type: "experiment", id: "S2", description: "Exploratory experiment", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], inputs: [], outputs: [], @@ -439,7 +435,7 @@ describe("scoreExperimentRigor", () => { type: "experiment" as const, id: "S2", description: "Experiment", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], inputs: [], outputs: [], diff --git a/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.ts b/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.ts index 27dde026761..b7758c1e5c5 100644 --- a/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.ts +++ b/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.ts @@ -14,7 +14,6 @@ */ import { - isParallelizable, type PlanSpec, type PlanStep, type StepType, @@ -108,7 +107,9 @@ export function scorePlanStructure( if (!validation.valid) { return { score: 0, - reason: `Invalid plan structure: ${validation.errors.length} validation errors. First error: ${validation.errors[0]?.message ?? "unknown"}`, + reason: `Invalid plan structure: ${validation.errors.length} validation errors. First error: ${ + validation.errors[0]?.message ?? "unknown" + }`, details, }; } @@ -126,7 +127,7 @@ export function scorePlanStructure( ); // Calculate parallelism ratio - const parallelizableSteps = plan.steps.filter(isParallelizable); + const parallelizableSteps = plan.steps.filter((step) => step.parallelizable); details.parallelismRatio = plan.steps.length > 0 ? parallelizableSteps.length / plan.steps.length : 0; @@ -273,7 +274,9 @@ export function scorePlanCoverage( const reason = `Requirements: ${details.coveredRequirementCount}/${details.requirementCount} covered ` + - `(must: ${(details.mustCoverageRatio * 100).toFixed(0)}%, should: ${(details.shouldCoverageRatio * 100).toFixed(0)}%). ` + + `(must: ${(details.mustCoverageRatio * 100).toFixed(0)}%, should: ${( + details.shouldCoverageRatio * 100 + ).toFixed(0)}%). ` + `Hypotheses: ${details.testedHypothesisCount}/${details.hypothesisCount} tested.`; return { score, reason, details }; diff --git a/apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts b/apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts index 72aa7d3b449..7da8aab8074 100644 --- a/apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts +++ b/apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts @@ -178,9 +178,9 @@ function formatStepForDisplay(step: PlanStep, depth: number): string[] { lines.push(`${indent}${icon} ${colorFn(step.id)} — ${step.description}`); // Dependencies - if (step.dependsOn.length > 0) { + if (step.dependencyIds.length > 0) { lines.push( - `${indent} ${color.dim(`depends on: ${step.dependsOn.join(", ")}`)}`, + `${indent} ${color.dim(`depends on: ${step.dependencyIds.join(", ")}`)}`, ); } @@ -234,8 +234,10 @@ function displayPlanVisualization(plan: PlanSpec): void { writeLine(color.bold("Execution Steps:")); // Group steps by their dependencies to show structure - const entrySteps = plan.steps.filter((step) => step.dependsOn.length === 0); - const otherSteps = plan.steps.filter((step) => step.dependsOn.length > 0); + const entrySteps = plan.steps.filter( + (step) => step.dependencyIds.length === 0, + ); + const otherSteps = plan.steps.filter((step) => step.dependencyIds.length > 0); // Show entry points (depth 0) if (entrySteps.length > 0) { diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts index 8f5c4036958..087216463cb 100644 --- a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts +++ b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts @@ -42,7 +42,7 @@ function createMinimalPlan(): PlanSpec { type: "research", id: "S1", description: "Single research step", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "findings", description: "Research findings" }], @@ -83,7 +83,7 @@ function createLinearPlan(): PlanSpec { type: "research", id: "S1", description: "Initial research", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "findings", description: "Initial findings" }], @@ -96,14 +96,11 @@ function createLinearPlan(): PlanSpec { type: "synthesize", id: "S2", description: "Synthesize findings", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], - inputs: [ - { name: "findings", description: "From S1", fromStepId: "S1" }, - ], + inputs: [{ name: "findings", description: "From S1" }], outputs: [{ name: "synthesis", description: "Synthesized results" }], mode: "integrative", - inputStepIds: ["S1"], parallelizable: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, @@ -111,11 +108,9 @@ function createLinearPlan(): PlanSpec { type: "develop", id: "S3", description: "Produce deliverable", - dependsOn: ["S2"], + dependencyIds: ["S2"], requirementIds: ["R1"], - inputs: [ - { name: "synthesis", description: "From S2", fromStepId: "S2" }, - ], + inputs: [{ name: "synthesis", description: "From S2" }], outputs: [{ name: "deliverable", description: "Final output" }], specification: "Build based on synthesis", deliverables: ["Documentation"], @@ -154,7 +149,7 @@ function createParallelPlan(): PlanSpec { type: "research", id: "S1", description: "Research topic A", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "findings_a", description: "Topic A findings" }], @@ -167,7 +162,7 @@ function createParallelPlan(): PlanSpec { type: "research", id: "S2", description: "Research topic B", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "findings_b", description: "Topic B findings" }], @@ -180,7 +175,7 @@ function createParallelPlan(): PlanSpec { type: "research", id: "S3", description: "Research topic C", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "findings_c", description: "Topic C findings" }], @@ -193,16 +188,15 @@ function createParallelPlan(): PlanSpec { type: "synthesize", id: "S4", description: "Combine all findings", - dependsOn: ["S1", "S2", "S3"], + dependencyIds: ["S1", "S2", "S3"], requirementIds: ["R1"], inputs: [ - { name: "findings_a", description: "From S1", fromStepId: "S1" }, - { name: "findings_b", description: "From S2", fromStepId: "S2" }, - { name: "findings_c", description: "From S3", fromStepId: "S3" }, + { name: "findings_a", description: "From S1" }, + { name: "findings_b", description: "From S2" }, + { name: "findings_c", description: "From S3" }, ], outputs: [{ name: "synthesis", description: "Combined synthesis" }], mode: "integrative", - inputStepIds: ["S1", "S2", "S3"], parallelizable: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, @@ -242,7 +236,7 @@ function createDiamondPlan(): PlanSpec { type: "research", id: "S1", description: "Initial research", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "initial", description: "Initial data" }], @@ -255,9 +249,9 @@ function createDiamondPlan(): PlanSpec { type: "research", id: "S2", description: "Branch A analysis", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], - inputs: [{ name: "initial", description: "From S1", fromStepId: "S1" }], + inputs: [{ name: "initial", description: "From S1" }], outputs: [{ name: "branch_a", description: "Branch A results" }], query: "Branch A query", stoppingRule: "Analyze branch A", @@ -268,9 +262,9 @@ function createDiamondPlan(): PlanSpec { type: "research", id: "S3", description: "Branch B analysis", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], - inputs: [{ name: "initial", description: "From S1", fromStepId: "S1" }], + inputs: [{ name: "initial", description: "From S1" }], outputs: [{ name: "branch_b", description: "Branch B results" }], query: "Branch B query", stoppingRule: "Analyze branch B", @@ -281,15 +275,14 @@ function createDiamondPlan(): PlanSpec { type: "synthesize", id: "S4", description: "Merge branches", - dependsOn: ["S2", "S3"], + dependencyIds: ["S2", "S3"], requirementIds: ["R1"], inputs: [ - { name: "branch_a", description: "From S2", fromStepId: "S2" }, - { name: "branch_b", description: "From S3", fromStepId: "S3" }, + { name: "branch_a", description: "From S2" }, + { name: "branch_b", description: "From S3" }, ], outputs: [{ name: "merged", description: "Merged results" }], mode: "integrative", - inputStepIds: ["S2", "S3"], parallelizable: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, @@ -325,7 +318,7 @@ function createMixedParallelismPlan(): PlanSpec { type: "research", id: "S1", description: "Parallelizable research", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "findings", description: "Findings" }], @@ -338,12 +331,11 @@ function createMixedParallelismPlan(): PlanSpec { type: "synthesize", id: "S2", description: "Non-parallelizable synthesis (no deps)", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "synthesis", description: "Synthesis" }], mode: "integrative", - inputStepIds: [], parallelizable: false, // Explicitly not parallelizable executor: { kind: "agent", ref: "result-synthesizer" }, }, @@ -351,7 +343,7 @@ function createMixedParallelismPlan(): PlanSpec { type: "develop", id: "S3", description: "Final development", - dependsOn: ["S1", "S2"], + dependencyIds: ["S1", "S2"], requirementIds: ["R1"], inputs: [], outputs: [{ name: "output", description: "Output" }], @@ -404,7 +396,7 @@ function createDeepDagPlan(): PlanSpec { type: "research", id: "S1", description: "Initial exploration of the problem space", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [ @@ -420,9 +412,9 @@ function createDeepDagPlan(): PlanSpec { type: "research", id: "S2", description: "Deep dive into area A", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], - inputs: [{ name: "context", description: "From S1", fromStepId: "S1" }], + inputs: [{ name: "context", description: "From S1" }], outputs: [{ name: "area_a_findings", description: "Area A findings" }], query: "Research area A in depth", stoppingRule: "Find 5 relevant sources", @@ -433,9 +425,9 @@ function createDeepDagPlan(): PlanSpec { type: "research", id: "S3", description: "Deep dive into area B", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], - inputs: [{ name: "context", description: "From S1", fromStepId: "S1" }], + inputs: [{ name: "context", description: "From S1" }], outputs: [{ name: "area_b_findings", description: "Area B findings" }], query: "Research area B in depth", stoppingRule: "Find 5 relevant sources", @@ -446,9 +438,9 @@ function createDeepDagPlan(): PlanSpec { type: "research", id: "S4", description: "Deep dive into area C", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], - inputs: [{ name: "context", description: "From S1", fromStepId: "S1" }], + inputs: [{ name: "context", description: "From S1" }], outputs: [{ name: "area_c_findings", description: "Area C findings" }], query: "Research area C in depth", stoppingRule: "Find 5 relevant sources", @@ -460,16 +452,15 @@ function createDeepDagPlan(): PlanSpec { type: "synthesize", id: "S5", description: "Combine findings from all research areas", - dependsOn: ["S2", "S3", "S4"], + dependencyIds: ["S2", "S3", "S4"], requirementIds: ["R2"], inputs: [ - { name: "area_a", description: "From S2", fromStepId: "S2" }, - { name: "area_b", description: "From S3", fromStepId: "S3" }, - { name: "area_c", description: "From S4", fromStepId: "S4" }, + { name: "area_a", description: "From S2" }, + { name: "area_b", description: "From S3" }, + { name: "area_c", description: "From S4" }, ], outputs: [{ name: "synthesis", description: "Combined synthesis" }], mode: "integrative", - inputStepIds: ["S2", "S3", "S4"], parallelizable: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, @@ -478,11 +469,9 @@ function createDeepDagPlan(): PlanSpec { type: "develop", id: "S6", description: "Develop component X based on synthesis", - dependsOn: ["S5"], + dependencyIds: ["S5"], requirementIds: ["R3"], - inputs: [ - { name: "synthesis", description: "From S5", fromStepId: "S5" }, - ], + inputs: [{ name: "synthesis", description: "From S5" }], outputs: [{ name: "component_x", description: "Component X" }], specification: "Build component X", deliverables: ["Component X implementation"], @@ -493,11 +482,9 @@ function createDeepDagPlan(): PlanSpec { type: "develop", id: "S7", description: "Develop component Y based on synthesis", - dependsOn: ["S5"], + dependencyIds: ["S5"], requirementIds: ["R3"], - inputs: [ - { name: "synthesis", description: "From S5", fromStepId: "S5" }, - ], + inputs: [{ name: "synthesis", description: "From S5" }], outputs: [{ name: "component_y", description: "Component Y" }], specification: "Build component Y", deliverables: ["Component Y implementation"], @@ -509,17 +496,16 @@ function createDeepDagPlan(): PlanSpec { type: "synthesize", id: "S8", description: "Evaluate and combine both components", - dependsOn: ["S6", "S7"], + dependencyIds: ["S6", "S7"], requirementIds: ["R2", "R3"], inputs: [ - { name: "component_x", description: "From S6", fromStepId: "S6" }, - { name: "component_y", description: "From S7", fromStepId: "S7" }, + { name: "component_x", description: "From S6" }, + { name: "component_y", description: "From S7" }, ], outputs: [ { name: "final_evaluation", description: "Final evaluation" }, ], mode: "evaluative", - inputStepIds: ["S6", "S7"], evaluateAgainst: [ "Do components integrate correctly?", "Are requirements met?", @@ -558,7 +544,7 @@ function createPlanWithInvalidExecutor(): PlanSpec { type: "research", id: "S1", description: "Step with nonexistent executor", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "findings", description: "Findings" }], @@ -593,7 +579,7 @@ function createPlanWithThrowingStep(): PlanSpec { type: "research", id: "S1", description: "__THROW__ This step should fail", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "findings", description: "Findings" }], diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts index 11f219a0a96..02a3b8487cb 100644 --- a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts +++ b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts @@ -61,7 +61,7 @@ export interface PlanStepStartEvent { description: string; depth: number; executor: Executor; - dependsOn: string[]; + dependencyIds: string[]; }; } @@ -272,7 +272,7 @@ function buildPromptForStep( case "synthesize": parts.push(`Mode: ${planStep.mode}`); - parts.push(`Input Step IDs: ${planStep.inputStepIds.join(", ")}`); + parts.push(`Dependencies: ${planStep.dependencyIds.join(", ")}`); if (planStep.mode === "evaluative" && planStep.evaluateAgainst) { parts.push(`Evaluate Against: ${planStep.evaluateAgainst.join(", ")}`); } @@ -443,7 +443,7 @@ function createMastraStep(planStep: PlanStep, ctx: CompilerContext) { description: planStep.description, depth, executor: planStep.executor, - dependsOn: planStep.dependsOn, + dependencyIds: planStep.dependencyIds, }, } satisfies PlanStepStartEvent); diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-validator.test.ts b/apps/hash-ai-agent/src/mastra/tools/plan-validator.test.ts index e975f65fa77..5da7921a764 100644 --- a/apps/hash-ai-agent/src/mastra/tools/plan-validator.test.ts +++ b/apps/hash-ai-agent/src/mastra/tools/plan-validator.test.ts @@ -44,7 +44,7 @@ function createBasePlan(): PlanSpec { type: "research", id: "S1", description: "Research step", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "findings", description: "Research findings" }], @@ -110,7 +110,7 @@ describe("Plan Validator — Negative Fixtures", () => { type: "research", id: "S1", // Duplicate! description: "Another research step", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [], @@ -170,9 +170,9 @@ describe("Plan Validator — Negative Fixtures", () => { // --------------------------------------------------------------------------- describe("INVALID_STEP_REFERENCE", () => { - test("rejects step with dependsOn referencing non-existent step", () => { + test("rejects step with dependencyIds referencing non-existent step", () => { const plan = createBasePlan(); - plan.steps[0]!.dependsOn = ["S99"]; // Non-existent + plan.steps[0]!.dependencyIds = ["S99"]; // Non-existent expectError(plan, "INVALID_STEP_REFERENCE"); @@ -180,50 +180,6 @@ describe("Plan Validator — Negative Fixtures", () => { const errors = getErrorsByCode(result, "INVALID_STEP_REFERENCE"); expect(errors[0]?.details?.invalidRef).toBe("S99"); }); - - test("rejects synthesize step with inputStepIds referencing non-existent step", () => { - const plan = createBasePlan(); - plan.steps.push({ - type: "synthesize", - id: "S2", - description: "Synthesize results", - dependsOn: ["S1"], - requirementIds: ["R1"], - inputs: [], - outputs: [], - mode: "integrative", - inputStepIds: ["S1", "S99"], // S99 doesn't exist - parallelizable: false, - executor: { kind: "agent", ref: "result-synthesizer" }, - }); - - expectError(plan, "INVALID_STEP_REFERENCE"); - }); - - test("rejects step with input.fromStepId referencing non-existent step", () => { - const plan = createBasePlan(); - plan.steps.push({ - type: "synthesize", - id: "S2", - description: "Synthesize results", - dependsOn: ["S1"], - requirementIds: ["R1"], - inputs: [ - { - name: "data", - description: "Input data", - fromStepId: "S99", // Non-existent - }, - ], - outputs: [], - mode: "integrative", - inputStepIds: ["S1"], - parallelizable: false, - executor: { kind: "agent", ref: "result-synthesizer" }, - }); - - expectError(plan, "INVALID_STEP_REFERENCE"); - }); }); describe("INVALID_HYPOTHESIS_REFERENCE", () => { @@ -242,7 +198,7 @@ describe("Plan Validator — Negative Fixtures", () => { type: "experiment", id: "S2", description: "Run experiment", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], inputs: [], outputs: [], @@ -322,7 +278,7 @@ describe("Plan Validator — Negative Fixtures", () => { type: "experiment", id: "S2", description: "Run experiment", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [], @@ -360,7 +316,7 @@ describe("Plan Validator — Negative Fixtures", () => { type: "experiment", id: "S2", description: "Confirmatory experiment", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [], @@ -392,7 +348,7 @@ describe("Plan Validator — Negative Fixtures", () => { type: "experiment", id: "S2", description: "Confirmatory experiment", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [], @@ -424,7 +380,7 @@ describe("Plan Validator — Negative Fixtures", () => { type: "experiment", id: "S2", description: "Exploratory experiment", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [], @@ -454,12 +410,11 @@ describe("Plan Validator — Negative Fixtures", () => { type: "synthesize", id: "S2", description: "Evaluate results", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], inputs: [], outputs: [], mode: "evaluative", // Requires evaluateAgainst! - inputStepIds: ["S1"], // Missing evaluateAgainst! parallelizable: false, executor: { kind: "agent", ref: "progress-evaluator" }, @@ -474,12 +429,11 @@ describe("Plan Validator — Negative Fixtures", () => { type: "synthesize", id: "S2", description: "Evaluate results", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], inputs: [], outputs: [], mode: "evaluative", - inputStepIds: ["S1"], evaluateAgainst: [], // Empty array! parallelizable: false, executor: { kind: "agent", ref: "progress-evaluator" }, @@ -494,12 +448,11 @@ describe("Plan Validator — Negative Fixtures", () => { type: "synthesize", id: "S2", description: "Combine findings", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], inputs: [], outputs: [], mode: "integrative", // Integrative doesn't require evaluateAgainst - inputStepIds: ["S1"], // No evaluateAgainst — OK for integrative parallelizable: false, executor: { kind: "agent", ref: "result-synthesizer" }, @@ -517,7 +470,7 @@ describe("Plan Validator — Negative Fixtures", () => { describe("CYCLE_DETECTED", () => { test("rejects plan with self-referencing step", () => { const plan = createBasePlan(); - plan.steps[0]!.dependsOn = ["S1"]; // Self-reference + plan.steps[0]!.dependencyIds = ["S1"]; // Self-reference expectError(plan, "CYCLE_DETECTED"); @@ -532,17 +485,16 @@ describe("Plan Validator — Negative Fixtures", () => { type: "synthesize", id: "S2", description: "Synthesize", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], inputs: [], outputs: [], mode: "integrative", - inputStepIds: ["S1"], parallelizable: false, executor: { kind: "agent", ref: "result-synthesizer" }, }); // Create cycle: S1 -> S2 -> S1 - plan.steps[0]!.dependsOn = ["S2"]; + plan.steps[0]!.dependencyIds = ["S2"]; expectError(plan, "CYCLE_DETECTED"); @@ -561,7 +513,7 @@ describe("Plan Validator — Negative Fixtures", () => { type: "research", id: "S2", description: "Research 2", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], inputs: [], outputs: [], @@ -574,7 +526,7 @@ describe("Plan Validator — Negative Fixtures", () => { type: "research", id: "S3", description: "Research 3", - dependsOn: ["S2"], + dependencyIds: ["S2"], requirementIds: ["R1"], inputs: [], outputs: [], @@ -585,7 +537,7 @@ describe("Plan Validator — Negative Fixtures", () => { }, ); // Create cycle: S1 -> S2 -> S3 -> S1 - plan.steps[0]!.dependsOn = ["S3"]; + plan.steps[0]!.dependencyIds = ["S3"]; expectError(plan, "CYCLE_DETECTED"); }); @@ -600,7 +552,7 @@ describe("Plan Validator — Negative Fixtures", () => { type: "research", id: "S1", description: "Initial research", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "findings", description: "Findings" }], @@ -613,7 +565,7 @@ describe("Plan Validator — Negative Fixtures", () => { type: "research", id: "S2", description: "Branch A", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], inputs: [], outputs: [], @@ -626,7 +578,7 @@ describe("Plan Validator — Negative Fixtures", () => { type: "research", id: "S3", description: "Branch B", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], inputs: [], outputs: [], @@ -639,12 +591,11 @@ describe("Plan Validator — Negative Fixtures", () => { type: "synthesize", id: "S4", description: "Combine branches", - dependsOn: ["S2", "S3"], + dependencyIds: ["S2", "S3"], requirementIds: ["R1"], inputs: [], outputs: [], mode: "integrative", - inputStepIds: ["S2", "S3"], parallelizable: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, @@ -674,7 +625,7 @@ describe("Plan Validator — Negative Fixtures", () => { type: "research", id: "S1", description: "Research", - dependsOn: ["S99"], // Invalid reference + dependencyIds: ["S99"], // Invalid reference requirementIds: ["R99"], // Invalid reference inputs: [], outputs: [], @@ -743,7 +694,7 @@ describe("Plan Validator — Negative Fixtures", () => { type: "research", id: "S1", description: "Literature review", - dependsOn: [], + dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "papers", description: "Relevant papers" }], @@ -756,14 +707,11 @@ describe("Plan Validator — Negative Fixtures", () => { type: "synthesize", id: "S2", description: "Summarize findings", - dependsOn: ["S1"], + dependencyIds: ["S1"], requirementIds: ["R1"], - inputs: [ - { name: "papers", description: "Papers", fromStepId: "S1" }, - ], + inputs: [{ name: "papers", description: "Papers" }], outputs: [{ name: "summary", description: "Literature summary" }], mode: "integrative", - inputStepIds: ["S1"], parallelizable: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, @@ -771,11 +719,9 @@ describe("Plan Validator — Negative Fixtures", () => { type: "experiment", id: "S3", description: "Test hypothesis", - dependsOn: ["S2"], + dependencyIds: ["S2"], requirementIds: ["R2"], - inputs: [ - { name: "summary", description: "Summary", fromStepId: "S2" }, - ], + inputs: [{ name: "summary", description: "Summary" }], outputs: [{ name: "results", description: "Experiment results" }], mode: "confirmatory", hypothesisIds: ["H1"], @@ -794,14 +740,11 @@ describe("Plan Validator — Negative Fixtures", () => { type: "synthesize", id: "S4", description: "Evaluate results", - dependsOn: ["S3"], + dependencyIds: ["S3"], requirementIds: ["R1", "R2"], - inputs: [ - { name: "results", description: "Results", fromStepId: "S3" }, - ], + inputs: [{ name: "results", description: "Results" }], outputs: [{ name: "conclusion", description: "Final conclusion" }], mode: "evaluative", - inputStepIds: ["S3"], evaluateAgainst: [ "Does the evidence support H1?", "What is the effect size?", diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-validator.ts b/apps/hash-ai-agent/src/mastra/tools/plan-validator.ts index 5df93289b36..d1620e9a292 100644 --- a/apps/hash-ai-agent/src/mastra/tools/plan-validator.ts +++ b/apps/hash-ai-agent/src/mastra/tools/plan-validator.ts @@ -7,7 +7,7 @@ * * Validation checks: * - DAG is acyclic (no circular dependencies) - * - All step references (dependsOn, inputStepIds, fromStepId) exist + * - All step references (dependencyIds) exist * - All hypothesis references exist * - All requirement references exist * - Executor references are in the available agents list @@ -19,17 +19,12 @@ * @see docs/PLAN-task-decomposition.md for design documentation */ -import { AVAILABLE_AGENTS, canAgentHandle } from "../constants"; +import { AVAILABLE_AGENTS, canAgentHandle } from "../agents/executor-agents"; import type { ExperimentStep, PlanSpec, SynthesizeStep, } from "../schemas/plan-spec"; -import { - getHypothesisReferences, - getRequirementReferences, - getStepReferences, -} from "../schemas/plan-spec"; // ============================================================================= // VALIDATION ERROR TYPES @@ -162,14 +157,14 @@ function validateUniqueRequirementIds(plan: PlanSpec): ValidationError[] { } /** - * Check that all step references (dependsOn, inputStepIds, fromStepId) exist. + * Check that all step references (dependencyIds) exist. */ function validateStepReferences(plan: PlanSpec): ValidationError[] { const errors: ValidationError[] = []; const stepIds = new Set(plan.steps.map((step) => step.id)); for (const step of plan.steps) { - const refs = getStepReferences(step); + const refs = step.dependencyIds; for (const ref of refs) { if (!stepIds.has(ref)) { errors.push({ @@ -193,7 +188,7 @@ function validateHypothesisReferences(plan: PlanSpec): ValidationError[] { const hypothesisIds = new Set(plan.hypotheses.map((hyp) => hyp.id)); for (const step of plan.steps) { - const refs = getHypothesisReferences(step); + const refs = step.type === "experiment" ? step.hypothesisIds : []; for (const ref of refs) { if (!hypothesisIds.has(ref)) { errors.push({ @@ -214,17 +209,17 @@ function validateHypothesisReferences(plan: PlanSpec): ValidationError[] { */ function validateRequirementReferences(plan: PlanSpec): ValidationError[] { const errors: ValidationError[] = []; - const requirementIds = new Set(plan.requirements.map((req) => req.id)); + const planReqs = new Set(plan.requirements.map((req) => req.id)); for (const step of plan.steps) { - const refs = getRequirementReferences(step); - for (const ref of refs) { - if (!requirementIds.has(ref)) { + const stepReqs = step.requirementIds; + for (const req of stepReqs) { + if (!planReqs.has(req)) { errors.push({ code: "INVALID_REQUIREMENT_REFERENCE", - message: `Step "${step.id}" references non-existent requirement "${ref}"`, + message: `Step "${step.id}" references non-existent requirement "${req}"`, context: step.id, - details: { invalidRef: ref }, + details: { invalidRef: req }, }); } } @@ -340,7 +335,7 @@ function detectCycle(plan: PlanSpec): string[] | null { // Build adjacency list (step -> steps it depends on) for (const step of plan.steps) { - const deps = getStepReferences(step).filter((ref) => stepIds.has(ref)); + const deps = step.dependencyIds.filter((ref) => stepIds.has(ref)); adjacency.set(step.id, deps); } diff --git a/apps/hash-ai-agent/src/mastra/tools/topology-analyzer.ts b/apps/hash-ai-agent/src/mastra/tools/topology-analyzer.ts index 3c2dfabcaa6..56aec8e288b 100644 --- a/apps/hash-ai-agent/src/mastra/tools/topology-analyzer.ts +++ b/apps/hash-ai-agent/src/mastra/tools/topology-analyzer.ts @@ -18,7 +18,6 @@ */ import type { PlanSpec, PlanStep } from "../schemas/plan-spec"; -import { getStepReferences, isParallelizable } from "../schemas/plan-spec"; // ============================================================================= // TYPES @@ -103,7 +102,7 @@ function buildGraphMaps(plan: PlanSpec): { // Populate from step references for (const step of plan.steps) { - const deps = getStepReferences(step).filter((ref) => stepIds.has(ref)); + const deps = step.dependencyIds.filter((ref) => stepIds.has(ref)); dependencies.set(step.id, new Set(deps)); for (const dep of deps) { @@ -215,7 +214,7 @@ function computeParallelGroups( const group = groupsByDepth.get(depth)!; group.stepIds.push(step.id); - if (isParallelizable(step)) { + if (step.parallelizable) { group.parallelizableStepIds.push(step.id); } } @@ -428,7 +427,7 @@ export function getUnblockedSteps( } // Check if all dependencies are completed - const deps = getStepReferences(step).filter((ref) => stepIds.has(ref)); + const deps = step.dependencyIds.filter((ref) => stepIds.has(ref)); const allDepsCompleted = deps.every((dep) => completedStepIds.has(dep)); if (allDepsCompleted) { diff --git a/apps/hash-ai-agent/src/mastra/workflows/revision-feedback.ts b/apps/hash-ai-agent/src/mastra/workflows/revision-feedback.ts index d5fad4dc2ed..6a27a7dbc22 100644 --- a/apps/hash-ai-agent/src/mastra/workflows/revision-feedback.ts +++ b/apps/hash-ai-agent/src/mastra/workflows/revision-feedback.ts @@ -30,7 +30,7 @@ function formatStepContext(step: PlanStep): string { id: step.id, type: step.type, description: step.description, - dependsOn: step.dependsOn, + dependencyIds: step.dependencyIds, }; // Add type-specific fields @@ -43,7 +43,6 @@ function formatStepContext(step: PlanStep): string { } } else if (step.type === "synthesize") { relevantFields.mode = step.mode; - relevantFields.inputStepIds = step.inputStepIds; if (step.mode === "evaluative") { relevantFields.evaluateAgainst = step.evaluateAgainst; } @@ -122,7 +121,7 @@ function getFixInstructions(error: ValidationError, _step?: PlanStep): string { CYCLE_DETECTED: dedent` The plan contains a circular dependency. Step "${error.context}" is part - of a cycle. Review the \`dependsOn\` references and ensure the plan forms + of a cycle. Review the \`dependencyIds\` references and ensure the plan forms a valid DAG (directed acyclic graph). `, @@ -130,8 +129,8 @@ function getFixInstructions(error: ValidationError, _step?: PlanStep): string { Step "${error.context}" references a step ID that doesn't exist. ${invalidRef ? `Invalid reference: "${invalidRef}"` : ""} - Check the \`dependsOn\`, \`inputStepIds\`, or \`fromStepId\` fields and - ensure they reference valid step IDs defined in the plan. + Check the \`dependencyIds\` field and ensure it references valid step IDs + defined in the plan. `, INVALID_HYPOTHESIS_REFERENCE: dedent` @@ -252,7 +251,7 @@ export function buildRevisionFeedback( When fixing these errors, ensure you: - Keep all existing step IDs stable unless they're duplicates - - Verify all references (hypothesisIds, requirementIds, dependsOn) point to existing IDs + - Verify all references (hypothesisIds, requirementIds, dependencyIds) point to existing IDs - Maintain the DAG structure (no circular dependencies) - Do not introduce new errors while fixing these From 2df4ae6a0e48c4b20a00f592bb530d43b3a2d765 Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 22 Dec 2025 13:54:40 +0100 Subject: [PATCH 09/16] remodel the parallelizable property --- .../src/mastra/agents/planner-agent.ts | 5 +- .../decomposition-prompts/ct-database-goal.ts | 2 +- .../explore-and-recommend.ts | 2 +- .../decomposition-prompts/fixtures.test.ts | 8 +-- .../hypothesis-validation.ts | 2 +- .../decomposition-prompts/mock-plans.ts | 44 +++++++------- .../decomposition-prompts/summarize-papers.ts | 2 +- .../src/mastra/schemas/plan-spec.ts | 48 ++++----------- .../src/mastra/schemas/planning-fixture.ts | 4 +- .../mastra/scorers/plan-llm-scorers.test.ts | 8 +-- .../src/mastra/scorers/plan-scorers.test.ts | 22 +++---- .../src/mastra/scorers/plan-scorers.ts | 12 ++-- .../src/mastra/tools/plan-compiler.test.ts | 60 +++++++++---------- .../src/mastra/tools/plan-compiler.ts | 20 +++---- .../src/mastra/tools/plan-validator.test.ts | 44 +++++++------- .../src/mastra/tools/topology-analyzer.ts | 18 +++--- 16 files changed, 137 insertions(+), 164 deletions(-) diff --git a/apps/hash-ai-agent/src/mastra/agents/planner-agent.ts b/apps/hash-ai-agent/src/mastra/agents/planner-agent.ts index 76eaa1e1db1..6d85f095abd 100644 --- a/apps/hash-ai-agent/src/mastra/agents/planner-agent.ts +++ b/apps/hash-ai-agent/src/mastra/agents/planner-agent.ts @@ -44,7 +44,6 @@ const PLANNER_INSTRUCTIONS = dedent` ### research - Use for: Gathering existing knowledge, literature review, exploring codebases - - Parallelizable: YES - multiple research queries can run concurrently - Must include: query (what to search for), stoppingRule (when research is "done") ### synthesize @@ -57,7 +56,7 @@ const PLANNER_INSTRUCTIONS = dedent` ### experiment - Use for: Testing hypotheses empirically, running prototypes, benchmarking - - Parallelizable: Can be parallel (independent experiments) or sequential + - Parallelism: Use dependencyIds for required ordering - Modes: - "exploratory": Hypothesis generation, flexible analysis - "confirmatory": Preregistered design, locked analysis plan @@ -125,6 +124,8 @@ Structure your uncertainties into four categories (all are required): - Generate unique IDs for requirements (R1, R2...), hypotheses (H1, H2...), and steps (S1, S2...) - Ensure dependencyIds references only existing step IDs + - If a step should NOT run concurrently with other ready steps for policy/resource reasons, + set "concurrent": false. Otherwise omit it (defaults to true). - Ensure hypothesisIds references only existing hypothesis IDs - Ensure requirementIds references only existing requirement IDs - Create a valid DAG (no circular dependencies) diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/ct-database-goal.ts b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/ct-database-goal.ts index 8cd231fa808..a57a6441164 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/ct-database-goal.ts +++ b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/ct-database-goal.ts @@ -63,7 +63,7 @@ export const ctDatabaseGoalFixture: PlanningFixture = { expected: { shouldHaveHypotheses: true, shouldHaveExperiments: true, - shouldHaveParallelResearch: true, + shouldHaveConcurrentResearch: true, minSteps: 8, maxSteps: 20, expectedStepTypes: ["research", "experiment", "synthesize", "develop"], diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/explore-and-recommend.ts b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/explore-and-recommend.ts index 7deb727a860..e5f8cd60ef6 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/explore-and-recommend.ts +++ b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/explore-and-recommend.ts @@ -42,7 +42,7 @@ export const exploreAndRecommendFixture: PlanningFixture = { // Note: LLM often generates hypotheses and experiments even when not strictly required shouldHaveHypotheses: false, // Not required, but may include shouldHaveExperiments: false, // Not required, but may include - shouldHaveParallelResearch: true, + shouldHaveConcurrentResearch: true, minSteps: 4, maxSteps: 12, // Increased to accommodate LLM's tendency to be thorough expectedStepTypes: ["research", "synthesize"], diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts index 066acd333e1..f0b6cbfcb4e 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts +++ b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts @@ -86,7 +86,7 @@ async function runFixtureTest(fixture: PlanningFixture): Promise { console.log(` Exit points: [${topology.exitPoints.join(", ")}]`); console.log(` Critical path: ${topology.criticalPath.length} steps`); console.log( - ` Max parallelism: ${Math.max(...topology.parallelGroups.map((group) => group.parallelizableStepIds.length))}`, + ` Max parallelism: ${Math.max(...topology.parallelGroups.map((group) => group.concurrentStepIds.length))}`, ); } @@ -117,10 +117,10 @@ async function runFixtureTest(fixture: PlanningFixture): Promise { expect(hasExperiment).toBe(true); } - // Parallel research expectation - if (expected.shouldHaveParallelResearch) { + // Concurrent research expectation + if (expected.shouldHaveConcurrentResearch) { const researchSteps = plan.steps.filter((step) => step.type === "research"); - // Should have at least one research step (all research steps are parallelizable by design) + // Should have at least one research step (typically concurrent by policy) expect(researchSteps.length).toBeGreaterThan(0); } diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/hypothesis-validation.ts b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/hypothesis-validation.ts index c271b8cb19b..b4f44066766 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/hypothesis-validation.ts +++ b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/hypothesis-validation.ts @@ -46,7 +46,7 @@ export const hypothesisValidationFixture: PlanningFixture = { expected: { shouldHaveHypotheses: true, shouldHaveExperiments: true, - shouldHaveParallelResearch: false, + shouldHaveConcurrentResearch: false, minSteps: 5, maxSteps: 15, expectedStepTypes: ["research", "experiment", "synthesize"], diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts index 3ed3c1726f2..5ff8792f97d 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts +++ b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts @@ -59,7 +59,7 @@ export const mockSummarizePapersPlan: PlanSpec = { "Recent retrieval-augmented generation architecture papers 2023-2024", stoppingRule: "Find 1 high-quality paper with clear architecture description", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -74,7 +74,7 @@ export const mockSummarizePapersPlan: PlanSpec = { ], query: "RAG retrieval methods dense sparse hybrid 2023-2024", stoppingRule: "Find 1 high-quality paper with novel retrieval approach", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -89,7 +89,7 @@ export const mockSummarizePapersPlan: PlanSpec = { ], query: "RAG performance benchmarks evaluation 2023-2024", stoppingRule: "Find 1 paper with comprehensive performance evaluation", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -110,7 +110,7 @@ export const mockSummarizePapersPlan: PlanSpec = { }, ], mode: "integrative", - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, ], @@ -196,7 +196,7 @@ export const mockExploreAndRecommendPlan: PlanSpec = { "HNSW hierarchical navigable small world index performance characteristics filtered queries", stoppingRule: "Understand latency at scale, memory requirements, and filtering support", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -216,7 +216,7 @@ export const mockExploreAndRecommendPlan: PlanSpec = { "IVF inverted file index vector database performance nlist nprobe tradeoffs", stoppingRule: "Understand build time, query latency, and accuracy tradeoffs", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -234,7 +234,7 @@ export const mockExploreAndRecommendPlan: PlanSpec = { ], query: "DiskANN ScaNN hybrid vector index billion scale filtered search", stoppingRule: "Identify 2-3 promising alternatives to HNSW and IVF", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -262,7 +262,7 @@ export const mockExploreAndRecommendPlan: PlanSpec = { }, ], mode: "integrative", - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, { @@ -290,7 +290,7 @@ export const mockExploreAndRecommendPlan: PlanSpec = { "Support for metadata filtering", "Index build time within 3-week timeline", ], - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "progress-evaluator" }, }, ], @@ -403,7 +403,7 @@ export const mockHypothesisValidationPlan: PlanSpec = { query: "Fine-tuning vs few-shot prompting named entity recognition legal documents comparison", stoppingRule: "Find 3+ relevant comparisons with quantitative results", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -436,7 +436,7 @@ export const mockHypothesisValidationPlan: PlanSpec = { "Complete evaluation on all test documents", "F1 score computed for each entity type", ], - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "experiment-runner" }, }, { @@ -464,7 +464,7 @@ export const mockHypothesisValidationPlan: PlanSpec = { "Training curves", "Validation F1 progression", ], - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "code-writer" }, }, { @@ -502,7 +502,7 @@ export const mockHypothesisValidationPlan: PlanSpec = { "Report all entity types, not just best performing", "Significance threshold: p < 0.05", ], - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "experiment-runner" }, }, { @@ -533,7 +533,7 @@ export const mockHypothesisValidationPlan: PlanSpec = { "Inference cost at 10K docs/day", "Stakeholder explainability", ], - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "progress-evaluator" }, }, ], @@ -660,7 +660,7 @@ export const mockCtDatabasePlan: PlanSpec = { query: "Category theory database foundations functorial data migration categorical query language", stoppingRule: "Identify key papers: Spivak, Schultz, CQL", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -676,7 +676,7 @@ export const mockCtDatabasePlan: PlanSpec = { query: "Category theory programming languages Haskell categorical semantics type theory", stoppingRule: "Understand how Haskell/ML encode CT concepts", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -697,7 +697,7 @@ export const mockCtDatabasePlan: PlanSpec = { "CQL categorical query language implementation Algebraic Databases performance", stoppingRule: "Document architecture, limitations, and performance of 2+ systems", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -727,7 +727,7 @@ export const mockCtDatabasePlan: PlanSpec = { }, ], mode: "integrative", - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, { @@ -760,7 +760,7 @@ export const mockCtDatabasePlan: PlanSpec = { "Complete implementation of basic structures", "Benchmark results for 3 query types", ], - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "experiment-runner" }, }, { @@ -795,7 +795,7 @@ export const mockCtDatabasePlan: PlanSpec = { "Warm cache for both", "Report median and p99 latency", ], - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "experiment-runner" }, }, { @@ -819,7 +819,7 @@ export const mockCtDatabasePlan: PlanSpec = { "Clear path to optimization", "Team has capacity for 6+ month project", ], - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "progress-evaluator" }, }, { @@ -843,7 +843,7 @@ export const mockCtDatabasePlan: PlanSpec = { "Query language parser", "Documentation", ], - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "code-writer" }, }, ], diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/summarize-papers.ts b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/summarize-papers.ts index f1cb5842e6d..74b3262c7a1 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/summarize-papers.ts +++ b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/summarize-papers.ts @@ -33,7 +33,7 @@ export const summarizePapersFixture: PlanningFixture = { expected: { shouldHaveHypotheses: false, shouldHaveExperiments: false, - shouldHaveParallelResearch: true, + shouldHaveConcurrentResearch: true, minSteps: 3, maxSteps: 6, expectedStepTypes: ["research", "synthesize"], diff --git a/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts b/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts index 818c5249c77..43a4b411457 100644 --- a/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts +++ b/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts @@ -15,10 +15,6 @@ import { z } from "zod"; -// ============================================================================= -// AIM TYPE -// ============================================================================= - /** * Classification of the goal's primary aim. * @@ -34,6 +30,9 @@ import { z } from "zod"; export const zAimType = z.enum(["describe", "explain", "predict", "intervene"]); export type AimType = z.infer; +/** + * Step types supported in the PlanSpec. + */ export const STEP_TYPES = [ "research", "synthesize", @@ -43,10 +42,6 @@ export const STEP_TYPES = [ export const zStepType = z.enum(STEP_TYPES); export type StepType = z.infer; -// ============================================================================= -// REQUIREMENTS -// ============================================================================= - /** * A requirement extracted from the goal. * @@ -64,10 +59,6 @@ export const zRequirement = z.object({ }); export type Requirement = z.infer; -// ============================================================================= -// HYPOTHESES -// ============================================================================= - /** * A testable hypothesis. * @@ -233,7 +224,12 @@ export const zBaseStep = z.object({ description: z.string().describe("What this step accomplishes"), dependencyIds: z .array(z.string()) + .default([]) .describe("Step IDs that must complete before this step"), + concurrent: z + .boolean() + .default(true) + .describe("Whether this step may run concurrently with other ready steps"), requirementIds: z .array(z.string()) .describe("Requirement IDs this step addresses"), @@ -256,9 +252,8 @@ export const zBaseStep = z.object({ /** * A research step for gathering existing knowledge. * - * Research steps are parallelizable — multiple research queries can run - * concurrently. Each research step should have a clear stopping rule - * defining what "done" means. + * Each research step should have a clear stopping rule defining what "done" + * means. */ export const zResearchStep = zBaseStep.extend({ type: zStepType.extract(["research"]), @@ -268,10 +263,6 @@ export const zResearchStep = zBaseStep.extend({ .describe( 'What "done" means for this research (e.g., "3 relevant papers found")', ), - parallelizable: z - .boolean() - .default(true) - .describe("Research steps are typically parallelizable (defaults to true)"), }); export type ResearchStep = z.infer; @@ -282,8 +273,6 @@ export type ResearchStep = z.infer; /** * A synthesize step for combining or evaluating results. * - * Synthesize steps are NOT parallelizable — they require all inputs to be ready. - * * When mode is 'evaluative', this subsumes the old "assess" step type. * Evaluative synthesis judges results against specific criteria. */ @@ -296,10 +285,6 @@ export const zSynthesizeStep = zBaseStep.extend({ .array(z.string()) .optional() .describe("Criteria to evaluate against (required if mode is evaluative)"), - parallelizable: z - .boolean() - .default(false) - .describe("Synthesize steps typically wait for inputs (defaults to false)"), }); export type SynthesizeStep = z.infer; @@ -323,9 +308,6 @@ export type ExperimentMode = z.infer; /** * An experiment step for testing hypotheses. * - * Experiment steps can be parallelizable — multiple independent experiments - * can run concurrently, but sequential experiments are also valid. - * * Confirmatory experiments SHOULD have preregisteredCommitments — decisions * locked before seeing outcomes. This is validated by the experiment-rigor scorer. */ @@ -346,10 +328,6 @@ export const zExperimentStep = zBaseStep.extend({ .describe( "Decisions locked before seeing outcomes (required for confirmatory)", ), - parallelizable: z - .boolean() - .default(true) - .describe("Whether this experiment can run in parallel with others"), }); export type ExperimentStep = z.infer; @@ -359,17 +337,11 @@ export type ExperimentStep = z.infer; /** * A develop step for building/implementing something. - * - * Develop steps may or may not be parallelizable depending on dependencies. */ export const zDevelopStep = zBaseStep.extend({ type: zStepType.extract(["develop"]), specification: z.string().describe("What to build/implement"), deliverables: z.array(z.string()).describe("Concrete outputs to produce"), - parallelizable: z - .boolean() - .default(false) - .describe("Whether this can run in parallel with other develop steps"), }); export type DevelopStep = z.infer; diff --git a/apps/hash-ai-agent/src/mastra/schemas/planning-fixture.ts b/apps/hash-ai-agent/src/mastra/schemas/planning-fixture.ts index 52b4dc1f49f..51dba4425d4 100644 --- a/apps/hash-ai-agent/src/mastra/schemas/planning-fixture.ts +++ b/apps/hash-ai-agent/src/mastra/schemas/planning-fixture.ts @@ -28,8 +28,8 @@ export interface ExpectedPlanCharacteristics { shouldHaveHypotheses: boolean; /** Should the plan include experiment steps? */ shouldHaveExperiments: boolean; - /** Should research steps be parallelizable? */ - shouldHaveParallelResearch: boolean; + /** Should research steps be concurrent? */ + shouldHaveConcurrentResearch: boolean; /** Minimum expected step count */ minSteps: number; /** Maximum expected step count (optional) */ diff --git a/apps/hash-ai-agent/src/mastra/scorers/plan-llm-scorers.test.ts b/apps/hash-ai-agent/src/mastra/scorers/plan-llm-scorers.test.ts index adab6b13e65..6ee70605975 100644 --- a/apps/hash-ai-agent/src/mastra/scorers/plan-llm-scorers.test.ts +++ b/apps/hash-ai-agent/src/mastra/scorers/plan-llm-scorers.test.ts @@ -54,7 +54,7 @@ function createMinimalTestPlan(): PlanSpec { outputs: [{ name: "papers", description: "Found papers" }], query: "retrieval augmented generation recent papers 2024", stoppingRule: "Find 3 relevant papers", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -66,7 +66,7 @@ function createMinimalTestPlan(): PlanSpec { inputs: [{ name: "papers", description: "Papers" }], outputs: [{ name: "comparison", description: "Comparison table" }], mode: "integrative", - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, ], @@ -132,7 +132,7 @@ function createPlanWithHypotheses(): PlanSpec { outputs: [{ name: "practices", description: "Best practices" }], query: "fine-tuning LLMs for entity extraction", stoppingRule: "Document 5 key practices", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -159,7 +159,7 @@ function createPlanWithHypotheses(): PlanSpec { "Primary metric: F1 score", "Significance threshold: p<0.05", ], - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "experiment-runner" }, }, ], diff --git a/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.test.ts b/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.test.ts index b954223ee91..516293510ad 100644 --- a/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.test.ts +++ b/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.test.ts @@ -42,7 +42,7 @@ function createMinimalPlan(): PlanSpec { outputs: [{ name: "findings", description: "Findings" }], query: "Query", stoppingRule: "Rule", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, ], @@ -100,7 +100,7 @@ function createComplexPlan(): PlanSpec { outputs: [{ name: "findings", description: "Findings" }], query: "Initial query", stoppingRule: "Find 5 sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -113,7 +113,7 @@ function createComplexPlan(): PlanSpec { outputs: [{ name: "data", description: "Data" }], query: "Parallel query", stoppingRule: "Collect data", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -128,7 +128,7 @@ function createComplexPlan(): PlanSpec { ], outputs: [{ name: "synthesis", description: "Combined understanding" }], mode: "integrative", - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, { @@ -145,7 +145,7 @@ function createComplexPlan(): PlanSpec { expectedOutcomes: ["H1 supported", "H1 refuted"], successCriteria: ["p < 0.05"], preregisteredCommitments: ["Sample size: 100", "Analysis: t-test"], - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "experiment-runner" }, }, { @@ -158,7 +158,7 @@ function createComplexPlan(): PlanSpec { outputs: [{ name: "prototype", description: "Working prototype" }], specification: "Build X based on findings", deliverables: ["Code", "Tests"], - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "code-writer" }, }, ], @@ -218,7 +218,7 @@ describe("scorePlanStructure", () => { inputs: [], outputs: [], mode: "integrative", - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "result-synthesizer" }, }); @@ -233,7 +233,7 @@ describe("scorePlanStructure", () => { outputs: [], query: "Query 2", stoppingRule: "Rule", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }); @@ -383,7 +383,7 @@ describe("scoreExperimentRigor", () => { expectedOutcomes: ["Outcome"], successCriteria: ["Criterion"], // No preregisteredCommitments! - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "experiment-runner" }, }); @@ -417,7 +417,7 @@ describe("scoreExperimentRigor", () => { procedure: "Procedure", expectedOutcomes: ["Outcome"], successCriteria: ["Criterion"], - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "experiment-runner" }, }); @@ -444,7 +444,7 @@ describe("scoreExperimentRigor", () => { procedure: "Procedure", expectedOutcomes: ["Outcome"], successCriteria: ["Criterion 1", "Criterion 2"], - parallelizable: true, + concurrent: true, executor: { kind: "agent" as const, ref: "experiment-runner" }, }; diff --git a/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.ts b/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.ts index b7758c1e5c5..bba5cb46c0c 100644 --- a/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.ts +++ b/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.ts @@ -56,7 +56,7 @@ export interface PlanStructureDetails { criticalPathLength: number; /** Maximum parallelism (max steps that can run concurrently) */ maxParallelism: number; - /** Ratio of parallelizable steps to total steps */ + /** Ratio of concurrent steps to total steps */ parallelismRatio: number; /** Step type distribution */ stepTypeDistribution: Record; @@ -121,15 +121,15 @@ export function scorePlanStructure( details.criticalPathLength = topology.criticalPath.length; details.maxParallelism = Math.max( 1, - ...topology.parallelGroups.map( - (group) => group.parallelizableStepIds.length, - ), + ...topology.parallelGroups.map((group) => group.concurrentStepIds.length), ); // Calculate parallelism ratio - const parallelizableSteps = plan.steps.filter((step) => step.parallelizable); + const concurrentSteps = plan.steps.filter( + (step) => step.concurrent !== false, + ); details.parallelismRatio = - plan.steps.length > 0 ? parallelizableSteps.length / plan.steps.length : 0; + plan.steps.length > 0 ? concurrentSteps.length / plan.steps.length : 0; // Calculate component scores const dagScore = 1.0; // Valid if we got here diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts index 087216463cb..999b8da5105 100644 --- a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts +++ b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts @@ -48,7 +48,7 @@ function createMinimalPlan(): PlanSpec { outputs: [{ name: "findings", description: "Research findings" }], query: "Test query", stoppingRule: "Find 3 sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, ], @@ -89,7 +89,7 @@ function createLinearPlan(): PlanSpec { outputs: [{ name: "findings", description: "Initial findings" }], query: "Initial query", stoppingRule: "Find sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -101,7 +101,7 @@ function createLinearPlan(): PlanSpec { inputs: [{ name: "findings", description: "From S1" }], outputs: [{ name: "synthesis", description: "Synthesized results" }], mode: "integrative", - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, { @@ -114,7 +114,7 @@ function createLinearPlan(): PlanSpec { outputs: [{ name: "deliverable", description: "Final output" }], specification: "Build based on synthesis", deliverables: ["Documentation"], - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "documentation-writer" }, }, ], @@ -155,7 +155,7 @@ function createParallelPlan(): PlanSpec { outputs: [{ name: "findings_a", description: "Topic A findings" }], query: "Topic A query", stoppingRule: "Find 3 sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -168,7 +168,7 @@ function createParallelPlan(): PlanSpec { outputs: [{ name: "findings_b", description: "Topic B findings" }], query: "Topic B query", stoppingRule: "Find 3 sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -181,7 +181,7 @@ function createParallelPlan(): PlanSpec { outputs: [{ name: "findings_c", description: "Topic C findings" }], query: "Topic C query", stoppingRule: "Find 3 sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -197,7 +197,7 @@ function createParallelPlan(): PlanSpec { ], outputs: [{ name: "synthesis", description: "Combined synthesis" }], mode: "integrative", - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, ], @@ -242,7 +242,7 @@ function createDiamondPlan(): PlanSpec { outputs: [{ name: "initial", description: "Initial data" }], query: "Initial query", stoppingRule: "Find sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -255,7 +255,7 @@ function createDiamondPlan(): PlanSpec { outputs: [{ name: "branch_a", description: "Branch A results" }], query: "Branch A query", stoppingRule: "Analyze branch A", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -268,7 +268,7 @@ function createDiamondPlan(): PlanSpec { outputs: [{ name: "branch_b", description: "Branch B results" }], query: "Branch B query", stoppingRule: "Analyze branch B", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -283,7 +283,7 @@ function createDiamondPlan(): PlanSpec { ], outputs: [{ name: "merged", description: "Merged results" }], mode: "integrative", - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, ], @@ -324,19 +324,19 @@ function createMixedParallelismPlan(): PlanSpec { outputs: [{ name: "findings", description: "Findings" }], query: "Query", stoppingRule: "Find sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { type: "synthesize", id: "S2", - description: "Non-parallelizable synthesis (no deps)", + description: "Non-concurrent synthesis (no deps)", dependencyIds: [], requirementIds: ["R1"], inputs: [], outputs: [{ name: "synthesis", description: "Synthesis" }], mode: "integrative", - parallelizable: false, // Explicitly not parallelizable + concurrent: false, // Explicitly not concurrent executor: { kind: "agent", ref: "result-synthesizer" }, }, { @@ -349,7 +349,7 @@ function createMixedParallelismPlan(): PlanSpec { outputs: [{ name: "output", description: "Output" }], specification: "Combine results", deliverables: ["Final artifact"], - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "documentation-writer" }, }, ], @@ -404,7 +404,7 @@ function createDeepDagPlan(): PlanSpec { ], query: "Explore problem space", stoppingRule: "Identify 3 key areas", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, // Depth 1: Parallel deep-dives @@ -418,7 +418,7 @@ function createDeepDagPlan(): PlanSpec { outputs: [{ name: "area_a_findings", description: "Area A findings" }], query: "Research area A in depth", stoppingRule: "Find 5 relevant sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -431,7 +431,7 @@ function createDeepDagPlan(): PlanSpec { outputs: [{ name: "area_b_findings", description: "Area B findings" }], query: "Research area B in depth", stoppingRule: "Find 5 relevant sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -444,7 +444,7 @@ function createDeepDagPlan(): PlanSpec { outputs: [{ name: "area_c_findings", description: "Area C findings" }], query: "Research area C in depth", stoppingRule: "Find 5 relevant sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, // Depth 2: Synthesis fan-in @@ -461,7 +461,7 @@ function createDeepDagPlan(): PlanSpec { ], outputs: [{ name: "synthesis", description: "Combined synthesis" }], mode: "integrative", - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, // Depth 3: Parallel development @@ -475,7 +475,7 @@ function createDeepDagPlan(): PlanSpec { outputs: [{ name: "component_x", description: "Component X" }], specification: "Build component X", deliverables: ["Component X implementation"], - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "code-writer" }, }, { @@ -488,7 +488,7 @@ function createDeepDagPlan(): PlanSpec { outputs: [{ name: "component_y", description: "Component Y" }], specification: "Build component Y", deliverables: ["Component Y implementation"], - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "code-writer" }, }, // Depth 4: Final synthesis/evaluation @@ -510,7 +510,7 @@ function createDeepDagPlan(): PlanSpec { "Do components integrate correctly?", "Are requirements met?", ], - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "progress-evaluator" }, }, ], @@ -550,7 +550,7 @@ function createPlanWithInvalidExecutor(): PlanSpec { outputs: [{ name: "findings", description: "Findings" }], query: "Test query", stoppingRule: "Find sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "nonexistent-agent" }, // Invalid! }, ], @@ -585,7 +585,7 @@ function createPlanWithThrowingStep(): PlanSpec { outputs: [{ name: "findings", description: "Findings" }], query: "__THROW__ trigger error", stoppingRule: "Find sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, ], @@ -753,15 +753,15 @@ describe("Plan Compiler — Topology Analysis", () => { expect(topology.criticalPath.stepIds[2]).toBe("S4"); }); - test("correctly identifies parallelizable steps within groups", () => { + test("correctly identifies concurrent steps within groups", () => { const plan = createMixedParallelismPlan(); const topology = analyzePlanTopology(plan); const depth0 = topology.parallelGroups.find((grp) => grp.depth === 0); - // S1 is parallelizable, S2 is not - expect(depth0?.parallelizableStepIds).toContain("S1"); - expect(depth0?.parallelizableStepIds).not.toContain("S2"); + // S1 is concurrent, S2 is not + expect(depth0?.concurrentStepIds).toContain("S1"); + expect(depth0?.concurrentStepIds).not.toContain("S2"); }); test("correctly computes 5 depth levels for deep DAG", () => { diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts index 02a3b8487cb..a162de791f4 100644 --- a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts +++ b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts @@ -500,7 +500,7 @@ function createMastraStep(planStep: PlanStep, ctx: CompilerContext) { * Strategy: * - Process parallel groups in order (by depth) * - Single step at a depth → .then() - * - Multiple parallelizable steps → .parallel() + * - Multiple concurrent steps → .parallel() * - Wrap with entry/exit handlers for streaming events */ function buildWorkflowFromGroups( @@ -581,19 +581,19 @@ function buildWorkflowFromGroups( // Single step - use .then() workflow.then(stepsInGroup[0]!); } else { - // Multiple steps - check if all are parallelizable - const parallelizableSteps = group.parallelizableStepIds + // Multiple steps - check if all are concurrent + const concurrentSteps = group.concurrentStepIds .map((id) => ctx.steps.get(id)) .filter((step): step is NonNullable => step !== undefined); - if (parallelizableSteps.length === stepsInGroup.length) { - // All parallelizable - use .parallel() - workflow.parallel(parallelizableSteps); - } else if (parallelizableSteps.length > 1) { + if (concurrentSteps.length === stepsInGroup.length) { + // All concurrent - use .parallel() + workflow.parallel(concurrentSteps); + } else if (concurrentSteps.length > 1) { // Mixed: parallel first, then sequential - workflow.parallel(parallelizableSteps); + workflow.parallel(concurrentSteps); const sequentialSteps = stepsInGroup.filter( - (step) => !parallelizableSteps.includes(step), + (step) => !concurrentSteps.includes(step), ); for (const step of sequentialSteps) { workflow.then(step); @@ -667,7 +667,7 @@ function buildWorkflowFromGroups( * 2. Create Mastra steps for each PlanStep with streaming instrumentation * 3. Build workflow using parallel groups: * - Single step at a depth → .then() - * - Multiple parallelizable steps at same depth → .parallel() + * - Multiple concurrent steps at same depth → .parallel() * * @param plan - A validated PlanSpec (call validatePlan first!) * @param options - Compilation options diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-validator.test.ts b/apps/hash-ai-agent/src/mastra/tools/plan-validator.test.ts index 5da7921a764..1f245120262 100644 --- a/apps/hash-ai-agent/src/mastra/tools/plan-validator.test.ts +++ b/apps/hash-ai-agent/src/mastra/tools/plan-validator.test.ts @@ -50,7 +50,7 @@ function createBasePlan(): PlanSpec { outputs: [{ name: "findings", description: "Research findings" }], query: "Test query", stoppingRule: "Find 3 relevant sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, ], @@ -116,7 +116,7 @@ describe("Plan Validator — Negative Fixtures", () => { outputs: [], query: "Another query", stoppingRule: "Find sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }); @@ -207,7 +207,7 @@ describe("Plan Validator — Negative Fixtures", () => { procedure: "Test procedure", expectedOutcomes: ["Outcome A"], successCriteria: ["Criterion A"], - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "experiment-runner" }, }); @@ -287,7 +287,7 @@ describe("Plan Validator — Negative Fixtures", () => { procedure: "Test procedure", expectedOutcomes: ["Outcome"], successCriteria: ["Criterion"], - parallelizable: true, + concurrent: true, // paper-summarizer can only handle "research" executor: { kind: "agent", ref: "paper-summarizer" }, }); @@ -326,7 +326,7 @@ describe("Plan Validator — Negative Fixtures", () => { expectedOutcomes: ["Outcome"], successCriteria: ["Criterion"], // Missing preregisteredCommitments! - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "experiment-runner" }, }); @@ -358,7 +358,7 @@ describe("Plan Validator — Negative Fixtures", () => { expectedOutcomes: ["Outcome"], successCriteria: ["Criterion"], preregisteredCommitments: [], // Empty array! - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "experiment-runner" }, }); @@ -390,7 +390,7 @@ describe("Plan Validator — Negative Fixtures", () => { expectedOutcomes: ["Outcome"], successCriteria: ["Criterion"], // No preregisteredCommitments — OK for exploratory - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "experiment-runner" }, }); @@ -416,7 +416,7 @@ describe("Plan Validator — Negative Fixtures", () => { outputs: [], mode: "evaluative", // Requires evaluateAgainst! // Missing evaluateAgainst! - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "progress-evaluator" }, }); @@ -435,7 +435,7 @@ describe("Plan Validator — Negative Fixtures", () => { outputs: [], mode: "evaluative", evaluateAgainst: [], // Empty array! - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "progress-evaluator" }, }); @@ -454,7 +454,7 @@ describe("Plan Validator — Negative Fixtures", () => { outputs: [], mode: "integrative", // Integrative doesn't require evaluateAgainst // No evaluateAgainst — OK for integrative - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "result-synthesizer" }, }); @@ -490,7 +490,7 @@ describe("Plan Validator — Negative Fixtures", () => { inputs: [], outputs: [], mode: "integrative", - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "result-synthesizer" }, }); // Create cycle: S1 -> S2 -> S1 @@ -519,7 +519,7 @@ describe("Plan Validator — Negative Fixtures", () => { outputs: [], query: "Query 2", stoppingRule: "Rule 2", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -532,7 +532,7 @@ describe("Plan Validator — Negative Fixtures", () => { outputs: [], query: "Query 3", stoppingRule: "Rule 3", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, ); @@ -558,7 +558,7 @@ describe("Plan Validator — Negative Fixtures", () => { outputs: [{ name: "findings", description: "Findings" }], query: "Initial query", stoppingRule: "Find sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -571,7 +571,7 @@ describe("Plan Validator — Negative Fixtures", () => { outputs: [], query: "Branch A query", stoppingRule: "Find sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -584,7 +584,7 @@ describe("Plan Validator — Negative Fixtures", () => { outputs: [], query: "Branch B query", stoppingRule: "Find sources", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -596,7 +596,7 @@ describe("Plan Validator — Negative Fixtures", () => { inputs: [], outputs: [], mode: "integrative", - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, ]; @@ -631,7 +631,7 @@ describe("Plan Validator — Negative Fixtures", () => { outputs: [], query: "Query", stoppingRule: "Rule", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "unknown-agent" }, // Invalid executor }, ], @@ -700,7 +700,7 @@ describe("Plan Validator — Negative Fixtures", () => { outputs: [{ name: "papers", description: "Relevant papers" }], query: "X and Y relationship", stoppingRule: "10 relevant papers", - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "literature-searcher" }, }, { @@ -712,7 +712,7 @@ describe("Plan Validator — Negative Fixtures", () => { inputs: [{ name: "papers", description: "Papers" }], outputs: [{ name: "summary", description: "Literature summary" }], mode: "integrative", - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "result-synthesizer" }, }, { @@ -733,7 +733,7 @@ describe("Plan Validator — Negative Fixtures", () => { "Analysis: t-test", "Stopping rule: fixed sample", ], - parallelizable: true, + concurrent: true, executor: { kind: "agent", ref: "experiment-runner" }, }, { @@ -750,7 +750,7 @@ describe("Plan Validator — Negative Fixtures", () => { "What is the effect size?", "Are there confounding factors?", ], - parallelizable: false, + concurrent: false, executor: { kind: "agent", ref: "progress-evaluator" }, }, ], diff --git a/apps/hash-ai-agent/src/mastra/tools/topology-analyzer.ts b/apps/hash-ai-agent/src/mastra/tools/topology-analyzer.ts index 56aec8e288b..c0d33f762b2 100644 --- a/apps/hash-ai-agent/src/mastra/tools/topology-analyzer.ts +++ b/apps/hash-ai-agent/src/mastra/tools/topology-analyzer.ts @@ -28,15 +28,15 @@ import type { PlanSpec, PlanStep } from "../schemas/plan-spec"; * * Steps in a group: * - Have the same dependency depth (all dependencies are satisfied at the same time) - * - May or may not be individually parallelizable (check `parallelizable` field) + * - May or may not be individually concurrent (check `concurrent` field) */ export interface ParallelGroup { /** Depth level (0 = entry points, 1 = depends on entry points, etc.) */ depth: number; /** Step IDs in this group */ stepIds: string[]; - /** Step IDs that are individually parallelizable */ - parallelizableStepIds: string[]; + /** Step IDs that are individually concurrent */ + concurrentStepIds: string[]; } /** @@ -207,15 +207,15 @@ function computeParallelGroups( groupsByDepth.set(depth, { depth, stepIds: [], - parallelizableStepIds: [], + concurrentStepIds: [], }); } const group = groupsByDepth.get(depth)!; group.stepIds.push(step.id); - if (step.parallelizable) { - group.parallelizableStepIds.push(step.id); + if (step.concurrent !== false) { + group.concurrentStepIds.push(step.id); } } @@ -346,7 +346,7 @@ function computeDependentCounts( * const analysis = analyzePlanTopology(planSpec); * * // Get steps that can run in parallel at depth 0 - * const firstBatch = analysis.parallelGroups[0].parallelizableStepIds; + * const firstBatch = analysis.parallelGroups[0].concurrentStepIds; * * // Check critical path length for complexity * console.log(`Critical path length: ${analysis.criticalPath.length}`); @@ -378,12 +378,12 @@ export function analyzePlanTopology(plan: PlanSpec): TopologyAnalysis { /** * Get the maximum parallelism possible at any depth level. * - * This is the maximum number of parallelizable steps in any single group. + * This is the maximum number of concurrent steps in any single group. */ export function getMaxParallelism(analysis: TopologyAnalysis): number { let max = 0; for (const group of analysis.parallelGroups) { - max = Math.max(max, group.parallelizableStepIds.length); + max = Math.max(max, group.concurrentStepIds.length); } return max; } From 81dbbb8d0acf30c76fafa1a3973f4637deb35c3d Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 22 Dec 2025 14:33:11 +0100 Subject: [PATCH 10/16] rename data-contract to step-artifact --- .../src/mastra/schemas/plan-spec.ts | 210 ++++++------------ .../src/mastra/tools/plan-compiler.ts | 6 +- 2 files changed, 70 insertions(+), 146 deletions(-) diff --git a/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts b/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts index 43a4b411457..c87a782d769 100644 --- a/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts +++ b/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts @@ -13,7 +13,7 @@ * @see docs/PLAN-task-decomposition.md for full design documentation */ -import { z } from "zod"; +import { z } from 'zod'; /** * Classification of the goal's primary aim. @@ -27,18 +27,13 @@ import { z } from "zod"; * Note: These are not mutually exclusive, so this is a weak signal for inference. * Included as optional enrichment — evaluate usefulness over time. */ -export const zAimType = z.enum(["describe", "explain", "predict", "intervene"]); +export const zAimType = z.enum(['describe', 'explain', 'predict', 'intervene']); export type AimType = z.infer; /** * Step types supported in the PlanSpec. */ -export const STEP_TYPES = [ - "research", - "synthesize", - "experiment", - "develop", -] as const; +export const STEP_TYPES = ['research', 'synthesize', 'experiment', 'develop'] as const; export const zStepType = z.enum(STEP_TYPES); export type StepType = z.infer; @@ -52,10 +47,8 @@ export type StepType = z.infer; */ export const zRequirement = z.object({ id: z.string().describe("Unique identifier (e.g., 'R1', 'R2')"), - description: z.string().describe("What needs to be achieved"), - priority: z - .enum(["must", "should", "could"]) - .describe("MoSCoW priority level"), + description: z.string().describe('What needs to be achieved'), + priority: z.enum(['must', 'should', 'could']).describe('MoSCoW priority level'), }); export type Requirement = z.infer; @@ -68,25 +61,15 @@ export type Requirement = z.infer; * - Validating that experiments reference valid hypotheses * - Scoring hypothesis testability */ -export const zHypothesisStatus = z.enum([ - "untested", - "testing", - "supported", - "refuted", - "inconclusive", -]); +export const zHypothesisStatus = z.enum(['untested', 'testing', 'supported', 'refuted', 'inconclusive']); export type HypothesisStatus = z.infer; export const zHypothesis = z.object({ id: z.string().describe("Unique identifier (e.g., 'H1', 'H2')"), - statement: z.string().describe("The hypothesis statement"), - assumptions: z - .array(z.string()) - .describe("Assumptions the hypothesis depends on"), - testableVia: z - .string() - .describe("How this hypothesis can be tested (what experiment/evidence)"), - status: zHypothesisStatus.default("untested"), + statement: z.string().describe('The hypothesis statement'), + assumptions: z.array(z.string()).describe('Assumptions the hypothesis depends on'), + testableVia: z.string().describe('How this hypothesis can be tested (what experiment/evidence)'), + status: zHypothesisStatus.default('untested'), }); export type Hypothesis = z.infer; @@ -102,10 +85,8 @@ export type Hypothesis = z.infer; * if our assumptions are wrong — a key scientific practice. */ export const zUnknownUnknown = z.object({ - potentialSurprise: z.string().describe("What would surprise us"), - detectionSignal: z - .string() - .describe("How would we notice? What would be the signal?"), + potentialSurprise: z.string().describe('What would surprise us'), + detectionSignal: z.string().describe('How would we notice? What would be the signal?'), }); export type UnknownUnknown = z.infer; @@ -124,60 +105,37 @@ export type UnknownUnknown = z.infer; * others would need to verify claims (science depends on communal scrutiny). */ export const zUnknownsMap = z.object({ - knownKnowns: z - .array(z.string()) - .describe("High-confidence facts we're building on"), - knownUnknowns: z - .array(z.string()) - .describe("Explicit questions we know we need to answer"), - unknownUnknowns: z - .array(zUnknownUnknown) - .describe("What would surprise us and how we'd detect it"), - communityCheck: z - .string() - .describe("What others would need to see to scrutinize our claims"), + knownKnowns: z.array(z.string()).describe("High-confidence facts we're building on"), + knownUnknowns: z.array(z.string()).describe('Explicit questions we know we need to answer'), + unknownUnknowns: z.array(zUnknownUnknown).describe("What would surprise us and how we'd detect it"), + communityCheck: z.string().describe('What others would need to see to scrutinize our claims'), }); export type UnknownsMap = z.infer; -// ============================================================================= -// DATA CONTRACTS -// ============================================================================= - /** - * A data contract describing step inputs/outputs. + * A step artifact describing step inputs/outputs. * * Contracts enable validation that steps are properly connected * and that data flows correctly through the plan. */ -export const zDataContract = z.object({ - name: z.string().describe("Name of the data artifact"), - description: z.string().describe("What this data represents"), +export const zStepArtifact = z.object({ + name: z.string().describe('Name of the data artifact'), + description: z.string().describe('What this data represents'), }); -export type DataContract = z.infer; - -// ============================================================================= -// EVALUATION CRITERIA -// ============================================================================= +export type StepArtifact = z.infer; /** * Criteria for evaluating step success. */ export const zEvalCriteria = z.object({ - successCondition: z.string().describe("What constitutes success"), - failureCondition: z - .string() - .optional() - .describe("What constitutes failure (if different from !success)"), + successCondition: z.string().describe('What constitutes success'), + failureCondition: z.string().optional().describe('What constitutes failure (if different from !success)'), }); export type EvalCriteria = z.infer; -// ============================================================================= -// EXECUTOR BINDING -// ============================================================================= - /** * Binding to an executor that will perform the step. * @@ -187,25 +145,22 @@ export type EvalCriteria = z.infer; * - workflow: A sub-workflow * - human: Requires human intervention */ -export const zExecutor = z.discriminatedUnion("kind", [ +export const zExecutor = z.discriminatedUnion('kind', [ z.object({ - kind: z.literal("agent"), - ref: z.string().describe("Agent identifier from AVAILABLE_AGENTS"), + kind: z.literal('agent'), + ref: z.string().describe('Agent identifier from AVAILABLE_AGENTS'), }), z.object({ - kind: z.literal("tool"), - ref: z.string().describe("Tool identifier"), + kind: z.literal('tool'), + ref: z.string().describe('Tool identifier'), }), z.object({ - kind: z.literal("workflow"), - ref: z.string().describe("Workflow identifier"), + kind: z.literal('workflow'), + ref: z.string().describe('Workflow identifier'), }), z.object({ - kind: z.literal("human"), - instructions: z - .string() - .optional() - .describe("Instructions for human executor"), + kind: z.literal('human'), + instructions: z.string().optional().describe('Instructions for human executor'), }), ]); @@ -221,24 +176,17 @@ export type Executor = z.infer; export const zBaseStep = z.object({ type: zStepType, id: z.string().describe("Unique identifier (e.g., 'S1', 'S2')"), - description: z.string().describe("What this step accomplishes"), - dependencyIds: z - .array(z.string()) - .default([]) - .describe("Step IDs that must complete before this step"), + description: z.string().describe('What this step accomplishes'), + dependencyIds: z.array(z.string()).default([]).describe('Step IDs that must complete before this step'), concurrent: z .boolean() .default(true) - .describe("Whether this step may run concurrently with other ready steps"), - requirementIds: z - .array(z.string()) - .describe("Requirement IDs this step addresses"), - inputs: z.array(zDataContract).describe("Data this step consumes"), - outputs: z.array(zDataContract).describe("Data this step produces"), - evalCriteria: zEvalCriteria - .optional() - .describe("How to evaluate step success"), - executor: zExecutor.describe("Who/what performs this step"), + .describe('Whether this step may run concurrently with other ready steps'), + requirementIds: z.array(z.string()).describe('Requirement IDs this step addresses'), + inputs: z.array(zStepArtifact).describe('Data this step consumes'), + outputs: z.array(zStepArtifact).describe('Data this step produces'), + evalCriteria: zEvalCriteria.optional().describe('How to evaluate step success'), + executor: zExecutor.describe('Who/what performs this step'), }); // ============================================================================= @@ -256,13 +204,9 @@ export const zBaseStep = z.object({ * means. */ export const zResearchStep = zBaseStep.extend({ - type: zStepType.extract(["research"]), - query: z.string().describe("The research question or search query"), - stoppingRule: z - .string() - .describe( - 'What "done" means for this research (e.g., "3 relevant papers found")', - ), + type: zStepType.extract(['research']), + query: z.string().describe('The research question or search query'), + stoppingRule: z.string().describe('What "done" means for this research (e.g., "3 relevant papers found")'), }); export type ResearchStep = z.infer; @@ -277,14 +221,12 @@ export type ResearchStep = z.infer; * Evaluative synthesis judges results against specific criteria. */ export const zSynthesizeStep = zBaseStep.extend({ - type: zStepType.extract(["synthesize"]), - mode: z - .enum(["integrative", "evaluative"]) - .describe("integrative (combine) or evaluative (judge)"), + type: zStepType.extract(['synthesize']), + mode: z.enum(['integrative', 'evaluative']).describe('integrative (combine) or evaluative (judge)'), evaluateAgainst: z .array(z.string()) .optional() - .describe("Criteria to evaluate against (required if mode is evaluative)"), + .describe('Criteria to evaluate against (required if mode is evaluative)'), }); export type SynthesizeStep = z.infer; @@ -302,7 +244,7 @@ export type SynthesizeStep = z.infer; * with preregistered commitments are more credible because decisions are locked * before seeing outcomes. */ -export const zExperimentMode = z.enum(["exploratory", "confirmatory"]); +export const zExperimentMode = z.enum(['exploratory', 'confirmatory']); export type ExperimentMode = z.infer; /** @@ -312,22 +254,16 @@ export type ExperimentMode = z.infer; * locked before seeing outcomes. This is validated by the experiment-rigor scorer. */ export const zExperimentStep = zBaseStep.extend({ - type: zStepType.extract(["experiment"]), - mode: zExperimentMode.describe("exploratory or confirmatory"), - hypothesisIds: z.array(z.string()).describe("Hypothesis IDs being tested"), - procedure: z.string().describe("How the experiment will be conducted"), - expectedOutcomes: z - .array(z.string()) - .describe("Possible outcomes and their interpretations"), - successCriteria: z - .array(z.string()) - .describe("What constitutes experimental success"), + type: zStepType.extract(['experiment']), + mode: zExperimentMode.describe('exploratory or confirmatory'), + hypothesisIds: z.array(z.string()).describe('Hypothesis IDs being tested'), + procedure: z.string().describe('How the experiment will be conducted'), + expectedOutcomes: z.array(z.string()).describe('Possible outcomes and their interpretations'), + successCriteria: z.array(z.string()).describe('What constitutes experimental success'), preregisteredCommitments: z .array(z.string()) .optional() - .describe( - "Decisions locked before seeing outcomes (required for confirmatory)", - ), + .describe('Decisions locked before seeing outcomes (required for confirmatory)'), }); export type ExperimentStep = z.infer; @@ -339,9 +275,9 @@ export type ExperimentStep = z.infer; * A develop step for building/implementing something. */ export const zDevelopStep = zBaseStep.extend({ - type: zStepType.extract(["develop"]), - specification: z.string().describe("What to build/implement"), - deliverables: z.array(z.string()).describe("Concrete outputs to produce"), + type: zStepType.extract(['develop']), + specification: z.string().describe('What to build/implement'), + deliverables: z.array(z.string()).describe('Concrete outputs to produce'), }); export type DevelopStep = z.infer; @@ -352,7 +288,7 @@ export type DevelopStep = z.infer; /** * A plan step — one of the 4 MVP step types. */ -export const zPlanStep = z.discriminatedUnion("type", [ +export const zPlanStep = z.discriminatedUnion('type', [ zResearchStep, zSynthesizeStep, zExperimentStep, @@ -367,7 +303,7 @@ export type PlanStep = z.infer; /** * Estimated complexity of the plan. */ -export const zComplexity = z.enum(["low", "medium", "high", "very-high"]); +export const zComplexity = z.enum(['low', 'medium', 'high', 'very-high']); export type Complexity = z.infer; /** @@ -385,31 +321,19 @@ export type Complexity = z.infer; * MVP scope: No decision points (deferred to v2). */ export const zPlanSpec = z.object({ - id: z.string().describe("Unique identifier for this plan"), - goalSummary: z - .string() - .describe("Concise summary of the goal being addressed"), + id: z.string().describe('Unique identifier for this plan'), + goalSummary: z.string().describe('Concise summary of the goal being addressed'), // Optional enrichment — aim type classification - aimType: zAimType - .optional() - .describe("Primary aim type: describe, explain, predict, or intervene"), + aimType: zAimType.optional().describe('Primary aim type: describe, explain, predict, or intervene'), // Core plan elements - requirements: z - .array(zRequirement) - .describe("Requirements extracted from the goal"), - hypotheses: z - .array(zHypothesis) - .describe("Hypotheses to be tested (may be empty for pure research)"), - steps: z.array(zPlanStep).describe("Steps forming a DAG"), - unknownsMap: zUnknownsMap.describe( - "Epistemically rigorous unknowns partition", - ), + requirements: z.array(zRequirement).describe('Requirements extracted from the goal'), + hypotheses: z.array(zHypothesis).describe('Hypotheses to be tested (may be empty for pure research)'), + steps: z.array(zPlanStep).describe('Steps forming a DAG'), + unknownsMap: zUnknownsMap.describe('Epistemically rigorous unknowns partition'), // Metadata - estimatedComplexity: zComplexity - .optional() - .describe("Estimated complexity of the plan"), + estimatedComplexity: zComplexity.optional().describe('Estimated complexity of the plan'), }); export type PlanSpec = z.infer; diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts index a162de791f4..24303182535 100644 --- a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts +++ b/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts @@ -221,7 +221,7 @@ export type CompiledWorkflowOutput = z.infer< // ============================================================================= /** - * Build input schema from step's data contracts. + * Build input schema from step artifacts. */ function buildInputSchema(planStep: PlanStep): z.ZodType { if (planStep.inputs.length === 0) { @@ -237,7 +237,7 @@ function buildInputSchema(planStep: PlanStep): z.ZodType { } /** - * Build output schema from step's data contracts. + * Build output schema from step artifacts. */ function buildOutputSchema(_planStep: PlanStep): z.ZodType { return z @@ -422,7 +422,7 @@ async function executeStep( function createMastraStep(planStep: PlanStep, ctx: CompilerContext) { const depth = ctx.topology.depthMap.get(planStep.id) ?? 0; - // Build input/output schemas from data contracts + // Build input/output schemas from step artifacts const inputSchema = buildInputSchema(planStep); const outputSchema = buildOutputSchema(planStep); From 5e18e6633309ef5a6382c2002bcba7852f78c82c Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 22 Dec 2025 14:37:40 +0100 Subject: [PATCH 11/16] move some files to more appropriate locations --- .../src/mastra/agents/planner-agent.ts | 2 +- .../decomposition-prompts/fixtures.test.ts | 10 +- .../src/mastra/schemas/plan-spec.ts | 210 +++++++++++------- .../mastra/scorers/plan-llm-scorers.test.ts | 2 +- .../src/mastra/scorers/plan-scorers.ts | 10 +- .../src/mastra/scripts/demo-plan-execution.ts | 30 ++- .../{fixtures => scripts}/generate-schemas.ts | 1 - .../build-revision-feedback.ts} | 57 +++-- .../src/mastra/{tools => utils}/mock-agent.ts | 0 .../{tools => utils}/plan-compiler.test.ts | 0 .../mastra/{tools => utils}/plan-compiler.ts | 0 .../plan-executors.ts} | 0 .../{tools => utils}/plan-validator.test.ts | 0 .../mastra/{tools => utils}/plan-validator.ts | 2 +- .../{tools => utils}/topology-analyzer.ts | 0 .../workflows/planning-workflow.test.ts | 8 +- .../src/mastra/workflows/planning-workflow.ts | 6 +- 17 files changed, 205 insertions(+), 133 deletions(-) rename apps/hash-ai-agent/src/mastra/{fixtures => scripts}/generate-schemas.ts (99%) rename apps/hash-ai-agent/src/mastra/{workflows/revision-feedback.ts => utils/build-revision-feedback.ts} (94%) rename apps/hash-ai-agent/src/mastra/{tools => utils}/mock-agent.ts (100%) rename apps/hash-ai-agent/src/mastra/{tools => utils}/plan-compiler.test.ts (100%) rename apps/hash-ai-agent/src/mastra/{tools => utils}/plan-compiler.ts (100%) rename apps/hash-ai-agent/src/mastra/{agents/executor-agents.ts => utils/plan-executors.ts} (100%) rename apps/hash-ai-agent/src/mastra/{tools => utils}/plan-validator.test.ts (100%) rename apps/hash-ai-agent/src/mastra/{tools => utils}/plan-validator.ts (99%) rename apps/hash-ai-agent/src/mastra/{tools => utils}/topology-analyzer.ts (100%) diff --git a/apps/hash-ai-agent/src/mastra/agents/planner-agent.ts b/apps/hash-ai-agent/src/mastra/agents/planner-agent.ts index 6d85f095abd..8941c6028b2 100644 --- a/apps/hash-ai-agent/src/mastra/agents/planner-agent.ts +++ b/apps/hash-ai-agent/src/mastra/agents/planner-agent.ts @@ -15,7 +15,7 @@ import dedent from "dedent"; import { DEFAULT_MODEL } from "../constants"; import type { PlanSpec } from "../schemas/plan-spec"; import { zPlanSpec } from "../schemas/plan-spec"; -import { formatAgentsForPrompt } from "./executor-agents"; +import { formatAgentsForPrompt } from "../utils/plan-executors"; /** * System instructions for the planner agent. diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts index f0b6cbfcb4e..fd7bb4c0ca9 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts +++ b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts @@ -14,8 +14,8 @@ import { describe, expect, test } from "vitest"; import { generatePlan } from "../../agents/planner-agent"; import type { PlanningFixture } from "../../schemas/planning-fixture"; -import { validatePlan } from "../../tools/plan-validator"; -import { analyzePlanTopology } from "../../tools/topology-analyzer"; +import { validatePlan } from "../../utils/plan-validator"; +import { analyzePlanTopology } from "../../utils/topology-analyzer"; import { ctDatabaseGoalFixture } from "./ct-database-goal"; import { exploreAndRecommendFixture } from "./explore-and-recommend"; import { hypothesisValidationFixture } from "./hypothesis-validation"; @@ -86,7 +86,11 @@ async function runFixtureTest(fixture: PlanningFixture): Promise { console.log(` Exit points: [${topology.exitPoints.join(", ")}]`); console.log(` Critical path: ${topology.criticalPath.length} steps`); console.log( - ` Max parallelism: ${Math.max(...topology.parallelGroups.map((group) => group.concurrentStepIds.length))}`, + ` Max parallelism: ${Math.max( + ...topology.parallelGroups.map( + (group) => group.concurrentStepIds.length, + ), + )}`, ); } diff --git a/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts b/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts index c87a782d769..142c20720ad 100644 --- a/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts +++ b/apps/hash-ai-agent/src/mastra/schemas/plan-spec.ts @@ -13,7 +13,7 @@ * @see docs/PLAN-task-decomposition.md for full design documentation */ -import { z } from 'zod'; +import { z } from "zod"; /** * Classification of the goal's primary aim. @@ -27,16 +27,9 @@ import { z } from 'zod'; * Note: These are not mutually exclusive, so this is a weak signal for inference. * Included as optional enrichment — evaluate usefulness over time. */ -export const zAimType = z.enum(['describe', 'explain', 'predict', 'intervene']); +export const zAimType = z.enum(["describe", "explain", "predict", "intervene"]); export type AimType = z.infer; -/** - * Step types supported in the PlanSpec. - */ -export const STEP_TYPES = ['research', 'synthesize', 'experiment', 'develop'] as const; -export const zStepType = z.enum(STEP_TYPES); -export type StepType = z.infer; - /** * A requirement extracted from the goal. * @@ -47,8 +40,10 @@ export type StepType = z.infer; */ export const zRequirement = z.object({ id: z.string().describe("Unique identifier (e.g., 'R1', 'R2')"), - description: z.string().describe('What needs to be achieved'), - priority: z.enum(['must', 'should', 'could']).describe('MoSCoW priority level'), + description: z.string().describe("What needs to be achieved"), + priority: z + .enum(["must", "should", "could"]) + .describe("MoSCoW priority level"), }); export type Requirement = z.infer; @@ -61,15 +56,25 @@ export type Requirement = z.infer; * - Validating that experiments reference valid hypotheses * - Scoring hypothesis testability */ -export const zHypothesisStatus = z.enum(['untested', 'testing', 'supported', 'refuted', 'inconclusive']); +export const zHypothesisStatus = z.enum([ + "untested", + "testing", + "supported", + "refuted", + "inconclusive", +]); export type HypothesisStatus = z.infer; export const zHypothesis = z.object({ id: z.string().describe("Unique identifier (e.g., 'H1', 'H2')"), - statement: z.string().describe('The hypothesis statement'), - assumptions: z.array(z.string()).describe('Assumptions the hypothesis depends on'), - testableVia: z.string().describe('How this hypothesis can be tested (what experiment/evidence)'), - status: zHypothesisStatus.default('untested'), + statement: z.string().describe("The hypothesis statement"), + assumptions: z + .array(z.string()) + .describe("Assumptions the hypothesis depends on"), + testableVia: z + .string() + .describe("How this hypothesis can be tested (what experiment/evidence)"), + status: zHypothesisStatus.default("untested"), }); export type Hypothesis = z.infer; @@ -85,8 +90,10 @@ export type Hypothesis = z.infer; * if our assumptions are wrong — a key scientific practice. */ export const zUnknownUnknown = z.object({ - potentialSurprise: z.string().describe('What would surprise us'), - detectionSignal: z.string().describe('How would we notice? What would be the signal?'), + potentialSurprise: z.string().describe("What would surprise us"), + detectionSignal: z + .string() + .describe("How would we notice? What would be the signal?"), }); export type UnknownUnknown = z.infer; @@ -105,10 +112,18 @@ export type UnknownUnknown = z.infer; * others would need to verify claims (science depends on communal scrutiny). */ export const zUnknownsMap = z.object({ - knownKnowns: z.array(z.string()).describe("High-confidence facts we're building on"), - knownUnknowns: z.array(z.string()).describe('Explicit questions we know we need to answer'), - unknownUnknowns: z.array(zUnknownUnknown).describe("What would surprise us and how we'd detect it"), - communityCheck: z.string().describe('What others would need to see to scrutinize our claims'), + knownKnowns: z + .array(z.string()) + .describe("High-confidence facts we're building on"), + knownUnknowns: z + .array(z.string()) + .describe("Explicit questions we know we need to answer"), + unknownUnknowns: z + .array(zUnknownUnknown) + .describe("What would surprise us and how we'd detect it"), + communityCheck: z + .string() + .describe("What others would need to see to scrutinize our claims"), }); export type UnknownsMap = z.infer; @@ -120,8 +135,8 @@ export type UnknownsMap = z.infer; * and that data flows correctly through the plan. */ export const zStepArtifact = z.object({ - name: z.string().describe('Name of the data artifact'), - description: z.string().describe('What this data represents'), + name: z.string().describe("Name of the data artifact"), + description: z.string().describe("What this data represents"), }); export type StepArtifact = z.infer; @@ -130,8 +145,11 @@ export type StepArtifact = z.infer; * Criteria for evaluating step success. */ export const zEvalCriteria = z.object({ - successCondition: z.string().describe('What constitutes success'), - failureCondition: z.string().optional().describe('What constitutes failure (if different from !success)'), + successCondition: z.string().describe("What constitutes success"), + failureCondition: z + .string() + .optional() + .describe("What constitutes failure (if different from !success)"), }); export type EvalCriteria = z.infer; @@ -145,54 +163,72 @@ export type EvalCriteria = z.infer; * - workflow: A sub-workflow * - human: Requires human intervention */ -export const zExecutor = z.discriminatedUnion('kind', [ +export const zExecutor = z.discriminatedUnion("kind", [ z.object({ - kind: z.literal('agent'), - ref: z.string().describe('Agent identifier from AVAILABLE_AGENTS'), + kind: z.literal("agent"), + ref: z.string().describe("Agent identifier from AVAILABLE_AGENTS"), }), z.object({ - kind: z.literal('tool'), - ref: z.string().describe('Tool identifier'), + kind: z.literal("tool"), + ref: z.string().describe("Tool identifier"), }), z.object({ - kind: z.literal('workflow'), - ref: z.string().describe('Workflow identifier'), + kind: z.literal("workflow"), + ref: z.string().describe("Workflow identifier"), }), z.object({ - kind: z.literal('human'), - instructions: z.string().optional().describe('Instructions for human executor'), + kind: z.literal("human"), + instructions: z + .string() + .optional() + .describe("Instructions for human executor"), }), ]); export type Executor = z.infer; // ============================================================================= -// BASE STEP +// STEP TYPES // ============================================================================= +/** + * Step types supported in the PlanSpec. + */ +export const STEP_TYPES = [ + "research", + "synthesize", + "experiment", + "develop", +] as const; +export const zStepType = z.enum(STEP_TYPES); +export type StepType = z.infer; + /** * Common fields shared by all step types. */ export const zBaseStep = z.object({ type: zStepType, id: z.string().describe("Unique identifier (e.g., 'S1', 'S2')"), - description: z.string().describe('What this step accomplishes'), - dependencyIds: z.array(z.string()).default([]).describe('Step IDs that must complete before this step'), + description: z.string().describe("What this step accomplishes"), + dependencyIds: z + .array(z.string()) + .default([]) + .describe("Step IDs that must complete before this step"), concurrent: z .boolean() .default(true) - .describe('Whether this step may run concurrently with other ready steps'), - requirementIds: z.array(z.string()).describe('Requirement IDs this step addresses'), - inputs: z.array(zStepArtifact).describe('Data this step consumes'), - outputs: z.array(zStepArtifact).describe('Data this step produces'), - evalCriteria: zEvalCriteria.optional().describe('How to evaluate step success'), - executor: zExecutor.describe('Who/what performs this step'), + .describe("Whether this step may run concurrently with other ready steps"), + requirementIds: z + .array(z.string()) + .describe("Requirement IDs this step addresses"), + inputs: z.array(zStepArtifact).describe("Data this step consumes"), + outputs: z.array(zStepArtifact).describe("Data this step produces"), + evalCriteria: zEvalCriteria + .optional() + .describe("How to evaluate step success"), + executor: zExecutor.describe("Who/what performs this step"), }); -// ============================================================================= -// STEP TYPES -// ============================================================================= - // ----------------------------------------------------------------------------- // Research Step // ----------------------------------------------------------------------------- @@ -204,9 +240,13 @@ export const zBaseStep = z.object({ * means. */ export const zResearchStep = zBaseStep.extend({ - type: zStepType.extract(['research']), - query: z.string().describe('The research question or search query'), - stoppingRule: z.string().describe('What "done" means for this research (e.g., "3 relevant papers found")'), + type: zStepType.extract(["research"]), + query: z.string().describe("The research question or search query"), + stoppingRule: z + .string() + .describe( + 'What "done" means for this research (e.g., "3 relevant papers found")', + ), }); export type ResearchStep = z.infer; @@ -221,12 +261,14 @@ export type ResearchStep = z.infer; * Evaluative synthesis judges results against specific criteria. */ export const zSynthesizeStep = zBaseStep.extend({ - type: zStepType.extract(['synthesize']), - mode: z.enum(['integrative', 'evaluative']).describe('integrative (combine) or evaluative (judge)'), + type: zStepType.extract(["synthesize"]), + mode: z + .enum(["integrative", "evaluative"]) + .describe("integrative (combine) or evaluative (judge)"), evaluateAgainst: z .array(z.string()) .optional() - .describe('Criteria to evaluate against (required if mode is evaluative)'), + .describe("Criteria to evaluate against (required if mode is evaluative)"), }); export type SynthesizeStep = z.infer; @@ -244,7 +286,7 @@ export type SynthesizeStep = z.infer; * with preregistered commitments are more credible because decisions are locked * before seeing outcomes. */ -export const zExperimentMode = z.enum(['exploratory', 'confirmatory']); +export const zExperimentMode = z.enum(["exploratory", "confirmatory"]); export type ExperimentMode = z.infer; /** @@ -254,16 +296,22 @@ export type ExperimentMode = z.infer; * locked before seeing outcomes. This is validated by the experiment-rigor scorer. */ export const zExperimentStep = zBaseStep.extend({ - type: zStepType.extract(['experiment']), - mode: zExperimentMode.describe('exploratory or confirmatory'), - hypothesisIds: z.array(z.string()).describe('Hypothesis IDs being tested'), - procedure: z.string().describe('How the experiment will be conducted'), - expectedOutcomes: z.array(z.string()).describe('Possible outcomes and their interpretations'), - successCriteria: z.array(z.string()).describe('What constitutes experimental success'), + type: zStepType.extract(["experiment"]), + mode: zExperimentMode.describe("exploratory or confirmatory"), + hypothesisIds: z.array(z.string()).describe("Hypothesis IDs being tested"), + procedure: z.string().describe("How the experiment will be conducted"), + expectedOutcomes: z + .array(z.string()) + .describe("Possible outcomes and their interpretations"), + successCriteria: z + .array(z.string()) + .describe("What constitutes experimental success"), preregisteredCommitments: z .array(z.string()) .optional() - .describe('Decisions locked before seeing outcomes (required for confirmatory)'), + .describe( + "Decisions locked before seeing outcomes (required for confirmatory)", + ), }); export type ExperimentStep = z.infer; @@ -275,9 +323,9 @@ export type ExperimentStep = z.infer; * A develop step for building/implementing something. */ export const zDevelopStep = zBaseStep.extend({ - type: zStepType.extract(['develop']), - specification: z.string().describe('What to build/implement'), - deliverables: z.array(z.string()).describe('Concrete outputs to produce'), + type: zStepType.extract(["develop"]), + specification: z.string().describe("What to build/implement"), + deliverables: z.array(z.string()).describe("Concrete outputs to produce"), }); export type DevelopStep = z.infer; @@ -288,7 +336,7 @@ export type DevelopStep = z.infer; /** * A plan step — one of the 4 MVP step types. */ -export const zPlanStep = z.discriminatedUnion('type', [ +export const zPlanStep = z.discriminatedUnion("type", [ zResearchStep, zSynthesizeStep, zExperimentStep, @@ -303,7 +351,7 @@ export type PlanStep = z.infer; /** * Estimated complexity of the plan. */ -export const zComplexity = z.enum(['low', 'medium', 'high', 'very-high']); +export const zComplexity = z.enum(["low", "medium", "high", "very-high"]); export type Complexity = z.infer; /** @@ -321,19 +369,31 @@ export type Complexity = z.infer; * MVP scope: No decision points (deferred to v2). */ export const zPlanSpec = z.object({ - id: z.string().describe('Unique identifier for this plan'), - goalSummary: z.string().describe('Concise summary of the goal being addressed'), + id: z.string().describe("Unique identifier for this plan"), + goalSummary: z + .string() + .describe("Concise summary of the goal being addressed"), // Optional enrichment — aim type classification - aimType: zAimType.optional().describe('Primary aim type: describe, explain, predict, or intervene'), + aimType: zAimType + .optional() + .describe("Primary aim type: describe, explain, predict, or intervene"), // Core plan elements - requirements: z.array(zRequirement).describe('Requirements extracted from the goal'), - hypotheses: z.array(zHypothesis).describe('Hypotheses to be tested (may be empty for pure research)'), - steps: z.array(zPlanStep).describe('Steps forming a DAG'), - unknownsMap: zUnknownsMap.describe('Epistemically rigorous unknowns partition'), + requirements: z + .array(zRequirement) + .describe("Requirements extracted from the goal"), + hypotheses: z + .array(zHypothesis) + .describe("Hypotheses to be tested (may be empty for pure research)"), + steps: z.array(zPlanStep).describe("Steps forming a DAG"), + unknownsMap: zUnknownsMap.describe( + "Epistemically rigorous unknowns partition", + ), // Metadata - estimatedComplexity: zComplexity.optional().describe('Estimated complexity of the plan'), + estimatedComplexity: zComplexity + .optional() + .describe("Estimated complexity of the plan"), }); export type PlanSpec = z.infer; diff --git a/apps/hash-ai-agent/src/mastra/scorers/plan-llm-scorers.test.ts b/apps/hash-ai-agent/src/mastra/scorers/plan-llm-scorers.test.ts index 6ee70605975..535adf21a8c 100644 --- a/apps/hash-ai-agent/src/mastra/scorers/plan-llm-scorers.test.ts +++ b/apps/hash-ai-agent/src/mastra/scorers/plan-llm-scorers.test.ts @@ -13,7 +13,7 @@ import { describe, expect, test } from "vitest"; import { generatePlan } from "../agents/planner-agent"; import type { PlanSpec } from "../schemas/plan-spec"; -import { validatePlan } from "../tools/plan-validator"; +import { validatePlan } from "../utils/plan-validator"; import { goalAlignmentScorer, hypothesisTestabilityScorer, diff --git a/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.ts b/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.ts index bba5cb46c0c..7ac60824901 100644 --- a/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.ts +++ b/apps/hash-ai-agent/src/mastra/scorers/plan-scorers.ts @@ -13,13 +13,9 @@ * Each scorer returns a normalized score [0, 1] and detailed breakdown. */ -import { - type PlanSpec, - type PlanStep, - type StepType, -} from "../schemas/plan-spec"; -import { validatePlan } from "../tools/plan-validator"; -import { analyzePlanTopology } from "../tools/topology-analyzer"; +import type { PlanSpec, PlanStep, StepType } from "../schemas/plan-spec"; +import { validatePlan } from "../utils/plan-validator"; +import { analyzePlanTopology } from "../utils/topology-analyzer"; // ============================================================================= // SCORER RESULT TYPES diff --git a/apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts b/apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts index 7da8aab8074..a6046061ee0 100644 --- a/apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts +++ b/apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts @@ -38,7 +38,7 @@ import type { import { compilePlanToWorkflow, type PlanExecutionEvent, -} from "../tools/plan-compiler"; +} from "../utils/plan-compiler"; import { planningWorkflow } from "../workflows/planning-workflow"; // ============================================================================= @@ -101,7 +101,7 @@ function parseCliArgs(): CliArgs { } else if (arg.startsWith("--fixture=")) { result.fixture = arg.split("=")[1]; } else if (arg.startsWith("--delay=")) { - result.delay = parseInt(arg.split("=")[1]!, 10); + result.delay = Number.parseInt(arg.split("=")[1]!, 10); } } @@ -383,7 +383,9 @@ async function executePlan( `${color.dim("┌")} Plan started: ${color.cyan(event.data.planId)}`, ); writeLine( - `${color.dim("│")} Steps: ${event.data.totalSteps}, Critical path: ${event.data.criticalPathLength}, Parallel groups: ${event.data.parallelGroups}`, + `${color.dim("│")} Steps: ${event.data.totalSteps}, Critical path: ${ + event.data.criticalPathLength + }, Parallel groups: ${event.data.parallelGroups}`, ); break; } @@ -396,7 +398,9 @@ async function executePlan( const depthIndicator = color.dim(`d${depth}`); writeLine( - `${color.dim("│")} ${color.yellow("▶")} ${formatStepType(stepType)} ${color.bold(stepId)} ${depthIndicator} — ${color.dim(description)}`, + `${color.dim("│")} ${color.yellow("▶")} ${formatStepType(stepType)} ${color.bold( + stepId, + )} ${depthIndicator} — ${color.dim(description)}`, ); if (stepInfo?.executor) { @@ -413,7 +417,11 @@ async function executePlan( completedSteps++; writeLine( - `${color.dim("│")} ${color.green("✓")} ${formatStepType(stepType)} ${color.bold(stepId)} ${color.dim(`(${formatDuration(durationMs)})`)} ${color.dim(`[${completedSteps}/${plan.steps.length}]`)}`, + `${color.dim("│")} ${color.green("✓")} ${formatStepType(stepType)} ${color.bold( + stepId, + )} ${color.dim(`(${formatDuration(durationMs)})`)} ${color.dim( + `[${completedSteps}/${plan.steps.length}]`, + )}`, ); break; } @@ -424,7 +432,9 @@ async function executePlan( errorCount++; writeLine( - `${color.dim("│")} ${color.red("✗")} ${formatStepType(stepType)} ${color.bold(stepId)} ${color.dim(`(${formatDuration(durationMs)})`)}`, + `${color.dim("│")} ${color.red("✗")} ${formatStepType(stepType)} ${color.bold(stepId)} ${color.dim( + `(${formatDuration(durationMs)})`, + )}`, ); writeLine(`${color.dim("│")} ${color.red(error)}`); break; @@ -439,7 +449,9 @@ async function executePlan( } = event.data; writeLine( - `${color.dim("├──")} Depth ${fromDepth} → ${toDepth} ${color.dim(`(${stepsCompletedAtDepth} done, ${stepsStartingAtDepth} starting)`)}`, + `${color.dim("├──")} Depth ${fromDepth} → ${toDepth} ${color.dim( + `(${stepsCompletedAtDepth} done, ${stepsStartingAtDepth} starting)`, + )}`, ); break; } @@ -459,7 +471,9 @@ async function executePlan( } = event.data; writeLine( - `${color.dim("└")} ${success ? color.green("Done") : color.red("Failed")}: ${planId} — ${color.cyan(formatDuration(totalDurationMs))}, ${stepsCompleted} completed, ${stepsFailed} failed`, + `${color.dim("└")} ${success ? color.green("Done") : color.red("Failed")}: ${planId} — ${color.cyan( + formatDuration(totalDurationMs), + )}, ${stepsCompleted} completed, ${stepsFailed} failed`, ); break; } diff --git a/apps/hash-ai-agent/src/mastra/fixtures/generate-schemas.ts b/apps/hash-ai-agent/src/mastra/scripts/generate-schemas.ts similarity index 99% rename from apps/hash-ai-agent/src/mastra/fixtures/generate-schemas.ts rename to apps/hash-ai-agent/src/mastra/scripts/generate-schemas.ts index a2c85b8e8b7..c4546588937 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/generate-schemas.ts +++ b/apps/hash-ai-agent/src/mastra/scripts/generate-schemas.ts @@ -1,4 +1,3 @@ -/* eslint-disable no-console */ /** * Script to generate bundled and dereferenced JSON Schema fixtures * from remote HASH type schemas. diff --git a/apps/hash-ai-agent/src/mastra/workflows/revision-feedback.ts b/apps/hash-ai-agent/src/mastra/utils/build-revision-feedback.ts similarity index 94% rename from apps/hash-ai-agent/src/mastra/workflows/revision-feedback.ts rename to apps/hash-ai-agent/src/mastra/utils/build-revision-feedback.ts index 6a27a7dbc22..fd12fc2f927 100644 --- a/apps/hash-ai-agent/src/mastra/workflows/revision-feedback.ts +++ b/apps/hash-ai-agent/src/mastra/utils/build-revision-feedback.ts @@ -11,10 +11,7 @@ import dedent from "dedent"; import type { PlanSpec, PlanStep } from "../schemas/plan-spec"; -import type { - ValidationError, - ValidationErrorCode, -} from "../tools/plan-validator"; +import type { ValidationError, ValidationErrorCode } from "./plan-validator"; // ============================================================================= // HELPERS (defined first to avoid use-before-define) @@ -85,13 +82,13 @@ function getFixInstructions(error: ValidationError, _step?: PlanStep): string { const instructions: Record = { MISSING_PREREGISTERED_COMMITMENTS: dedent` - **CRITICAL ERROR**: Step "${error.context}" is a confirmatory experiment but is - MISSING the REQUIRED \`preregisteredCommitments\` array. This field is mandatory + **CRITICAL ERROR**: Step "${error.context}" is a confirmatory experiment but is + MISSING the REQUIRED \`preregisteredCommitments\` array. This field is mandatory for all confirmatory experiments. - - You MUST add a preregisteredCommitments array with 2-3 specific commitments + + You MUST add a preregisteredCommitments array with 2-3 specific commitments that lock decisions BEFORE seeing outcomes: - + Example fix for step "${error.context}": \`\`\`json "preregisteredCommitments": [ @@ -100,15 +97,15 @@ function getFixInstructions(error: ValidationError, _step?: PlanStep): string { "Success threshold: " ] \`\`\` - - If you cannot specify preregistered commitments, change the experiment mode + + If you cannot specify preregistered commitments, change the experiment mode from "confirmatory" to "exploratory" instead. `, MISSING_EVALUATE_AGAINST: dedent` - Step "${error.context}" is an evaluative synthesize step but is missing + Step "${error.context}" is an evaluative synthesize step but is missing the required \`evaluateAgainst\` array. - + Add 2-3 specific criteria that results will be evaluated against: - Relevant requirements or hypotheses to check - Specific metrics or quality thresholds @@ -120,67 +117,67 @@ function getFixInstructions(error: ValidationError, _step?: PlanStep): string { `, CYCLE_DETECTED: dedent` - The plan contains a circular dependency. Step "${error.context}" is part - of a cycle. Review the \`dependencyIds\` references and ensure the plan forms + The plan contains a circular dependency. Step "${error.context}" is part + of a cycle. Review the \`dependencyIds\` references and ensure the plan forms a valid DAG (directed acyclic graph). `, INVALID_STEP_REFERENCE: dedent` Step "${error.context}" references a step ID that doesn't exist. ${invalidRef ? `Invalid reference: "${invalidRef}"` : ""} - - Check the \`dependencyIds\` field and ensure it references valid step IDs + + Check the \`dependencyIds\` field and ensure it references valid step IDs defined in the plan. `, INVALID_HYPOTHESIS_REFERENCE: dedent` Step "${error.context}" references a hypothesis ID that doesn't exist. ${invalidRef ? `Invalid reference: "${invalidRef}"` : ""} - - Check the \`hypothesisIds\` field and ensure it references valid hypothesis + + Check the \`hypothesisIds\` field and ensure it references valid hypothesis IDs defined in the plan's \`hypotheses\` array. `, INVALID_REQUIREMENT_REFERENCE: dedent` Step "${error.context}" references a requirement ID that doesn't exist. ${invalidRef ? `Invalid reference: "${invalidRef}"` : ""} - - Check the \`requirementIds\` field and ensure it references valid requirement + + Check the \`requirementIds\` field and ensure it references valid requirement IDs defined in the plan's \`requirements\` array. `, INVALID_EXECUTOR_REFERENCE: dedent` Step "${error.context}" references an executor that doesn't exist. ${invalidRef ? `Invalid executor ref: "${invalidRef}"` : ""} - + Use a valid executor from the available agents list provided in the prompt. `, EXECUTOR_CANNOT_HANDLE_STEP: dedent` - Step "${error.context}" is assigned to an executor that cannot handle + Step "${error.context}" is assigned to an executor that cannot handle its step type. ${executor ? `Executor: "${executor}"` : ""} ${stepType ? `Step type: "${stepType}"` : ""} - - Assign an executor that supports the step type, or change the step type + + Assign an executor that supports the step type, or change the step type to match the executor's capabilities. `, DUPLICATE_STEP_ID: dedent` Multiple steps have the same ID: "${error.context}". - + Each step must have a unique ID. Rename one of the duplicate steps. `, DUPLICATE_HYPOTHESIS_ID: dedent` Multiple hypotheses have the same ID: "${error.context}". - + Each hypothesis must have a unique ID. Rename one of the duplicates. `, DUPLICATE_REQUIREMENT_ID: dedent` Multiple requirements have the same ID: "${error.context}". - + Each requirement must have a unique ID. Rename one of the duplicates. `, }; @@ -193,7 +190,7 @@ function getFixInstructions(error: ValidationError, _step?: PlanStep): string { // Fallback for any unhandled error codes return dedent` Fix the ${error.code} error${error.context ? ` on "${error.context}"` : ""}. - + Error message: ${error.message} `; } @@ -242,7 +239,7 @@ export function buildRevisionFeedback( return dedent` ## Revision Required - Your previous plan failed validation with ${errors.length} error${errors.length > 1 ? "s" : ""}. + Your previous plan failed validation with ${errors.length} error${errors.length > 1 ? "s" : ""}. Fix ALL errors in a single revision. ${errorSections.join("\n\n---\n\n")} diff --git a/apps/hash-ai-agent/src/mastra/tools/mock-agent.ts b/apps/hash-ai-agent/src/mastra/utils/mock-agent.ts similarity index 100% rename from apps/hash-ai-agent/src/mastra/tools/mock-agent.ts rename to apps/hash-ai-agent/src/mastra/utils/mock-agent.ts diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts b/apps/hash-ai-agent/src/mastra/utils/plan-compiler.test.ts similarity index 100% rename from apps/hash-ai-agent/src/mastra/tools/plan-compiler.test.ts rename to apps/hash-ai-agent/src/mastra/utils/plan-compiler.test.ts diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts b/apps/hash-ai-agent/src/mastra/utils/plan-compiler.ts similarity index 100% rename from apps/hash-ai-agent/src/mastra/tools/plan-compiler.ts rename to apps/hash-ai-agent/src/mastra/utils/plan-compiler.ts diff --git a/apps/hash-ai-agent/src/mastra/agents/executor-agents.ts b/apps/hash-ai-agent/src/mastra/utils/plan-executors.ts similarity index 100% rename from apps/hash-ai-agent/src/mastra/agents/executor-agents.ts rename to apps/hash-ai-agent/src/mastra/utils/plan-executors.ts diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-validator.test.ts b/apps/hash-ai-agent/src/mastra/utils/plan-validator.test.ts similarity index 100% rename from apps/hash-ai-agent/src/mastra/tools/plan-validator.test.ts rename to apps/hash-ai-agent/src/mastra/utils/plan-validator.test.ts diff --git a/apps/hash-ai-agent/src/mastra/tools/plan-validator.ts b/apps/hash-ai-agent/src/mastra/utils/plan-validator.ts similarity index 99% rename from apps/hash-ai-agent/src/mastra/tools/plan-validator.ts rename to apps/hash-ai-agent/src/mastra/utils/plan-validator.ts index d1620e9a292..120d4a0a94d 100644 --- a/apps/hash-ai-agent/src/mastra/tools/plan-validator.ts +++ b/apps/hash-ai-agent/src/mastra/utils/plan-validator.ts @@ -19,12 +19,12 @@ * @see docs/PLAN-task-decomposition.md for design documentation */ -import { AVAILABLE_AGENTS, canAgentHandle } from "../agents/executor-agents"; import type { ExperimentStep, PlanSpec, SynthesizeStep, } from "../schemas/plan-spec"; +import { AVAILABLE_AGENTS, canAgentHandle } from "./plan-executors"; // ============================================================================= // VALIDATION ERROR TYPES diff --git a/apps/hash-ai-agent/src/mastra/tools/topology-analyzer.ts b/apps/hash-ai-agent/src/mastra/utils/topology-analyzer.ts similarity index 100% rename from apps/hash-ai-agent/src/mastra/tools/topology-analyzer.ts rename to apps/hash-ai-agent/src/mastra/utils/topology-analyzer.ts diff --git a/apps/hash-ai-agent/src/mastra/workflows/planning-workflow.test.ts b/apps/hash-ai-agent/src/mastra/workflows/planning-workflow.test.ts index 3cb2e9f0ed6..bee7dbd3828 100644 --- a/apps/hash-ai-agent/src/mastra/workflows/planning-workflow.test.ts +++ b/apps/hash-ai-agent/src/mastra/workflows/planning-workflow.test.ts @@ -24,11 +24,11 @@ import { type CompositePlanScore, scorePlanComposite, } from "../scorers/plan-scorers"; -import { validatePlan, type ValidationResult } from "../tools/plan-validator"; +import { validatePlan, type ValidationResult } from "../utils/plan-validator"; import { analyzePlanTopology, type TopologyAnalysis, -} from "../tools/topology-analyzer"; +} from "../utils/topology-analyzer"; import { planningWorkflow } from "./planning-workflow"; // ============================================================================= @@ -597,7 +597,9 @@ describeIfLlm("Planning Workflow with Revision Loop", () => { durationMs, }); console.log( - ` Valid: ${output.valid}, Attempts: ${output.attempts}, Steps: ${output.plan.steps.length}, Duration: ${(durationMs / 1000).toFixed(1)}s`, + ` Valid: ${output.valid}, Attempts: ${output.attempts}, Steps: ${ + output.plan.steps.length + }, Duration: ${(durationMs / 1000).toFixed(1)}s`, ); } else { results.push({ diff --git a/apps/hash-ai-agent/src/mastra/workflows/planning-workflow.ts b/apps/hash-ai-agent/src/mastra/workflows/planning-workflow.ts index 9a56a529667..4290fa46be6 100644 --- a/apps/hash-ai-agent/src/mastra/workflows/planning-workflow.ts +++ b/apps/hash-ai-agent/src/mastra/workflows/planning-workflow.ts @@ -18,9 +18,9 @@ import { z } from "zod"; import { generatePlan } from "../agents/planner-agent"; import { zPlanSpec } from "../schemas/plan-spec"; -import type { ValidationError } from "../tools/plan-validator"; -import { validatePlan } from "../tools/plan-validator"; -import { buildRevisionFeedback } from "./revision-feedback"; +import { buildRevisionFeedback } from "../utils/build-revision-feedback"; +import type { ValidationError } from "../utils/plan-validator"; +import { validatePlan } from "../utils/plan-validator"; // ============================================================================= // SCHEMAS From 7363d742808bccf53835c3ad42a757a9973a87b5 Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 22 Dec 2025 15:05:40 +0100 Subject: [PATCH 12/16] clean up fixtures directory --- .../planner-agent.test.ts} | 18 +- .../decomposition-prompts/fixtures.ts | 34 -- .../entity-schemas/organization.bundled.json | 4 +- .../organization.dereferenced.json | 4 +- .../{decomposition-prompts => }/mock-plans.ts | 2 +- .../ct-database-goal.ts | 30 +- .../explore-and-recommend.ts | 12 +- .../hypothesis-validation.ts | 18 +- .../summarize-papers.ts | 10 +- .../{planning-fixture.ts => planning-goal.ts} | 2 +- .../src/mastra/scripts/generate-schemas.ts | 4 +- ...tion.ts => planning-workflow-mock-demo.ts} | 20 +- .../workflows/planning-workflow.test.ts | 578 +----------------- 13 files changed, 81 insertions(+), 655 deletions(-) rename apps/hash-ai-agent/src/mastra/{fixtures/decomposition-prompts/fixtures.test.ts => agents/planner-agent.test.ts} (89%) delete mode 100644 apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.ts rename apps/hash-ai-agent/src/mastra/fixtures/{decomposition-prompts => }/mock-plans.ts (99%) rename apps/hash-ai-agent/src/mastra/fixtures/{decomposition-prompts => planning-goals}/ct-database-goal.ts (91%) rename apps/hash-ai-agent/src/mastra/fixtures/{decomposition-prompts => planning-goals}/explore-and-recommend.ts (92%) rename apps/hash-ai-agent/src/mastra/fixtures/{decomposition-prompts => planning-goals}/hypothesis-validation.ts (91%) rename apps/hash-ai-agent/src/mastra/fixtures/{decomposition-prompts => planning-goals}/summarize-papers.ts (89%) rename apps/hash-ai-agent/src/mastra/schemas/{planning-fixture.ts => planning-goal.ts} (97%) rename apps/hash-ai-agent/src/mastra/scripts/{demo-plan-execution.ts => planning-workflow-mock-demo.ts} (97%) diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts b/apps/hash-ai-agent/src/mastra/agents/planner-agent.test.ts similarity index 89% rename from apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts rename to apps/hash-ai-agent/src/mastra/agents/planner-agent.test.ts index fd7bb4c0ca9..efca154a19c 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.test.ts +++ b/apps/hash-ai-agent/src/mastra/agents/planner-agent.test.ts @@ -12,14 +12,14 @@ import { describe, expect, test } from "vitest"; -import { generatePlan } from "../../agents/planner-agent"; -import type { PlanningFixture } from "../../schemas/planning-fixture"; -import { validatePlan } from "../../utils/plan-validator"; -import { analyzePlanTopology } from "../../utils/topology-analyzer"; -import { ctDatabaseGoalFixture } from "./ct-database-goal"; -import { exploreAndRecommendFixture } from "./explore-and-recommend"; -import { hypothesisValidationFixture } from "./hypothesis-validation"; -import { summarizePapersFixture } from "./summarize-papers"; +import { ctDatabaseGoalFixture } from "../fixtures/planning-goals/ct-database-goal"; +import { exploreAndRecommendFixture } from "../fixtures/planning-goals/explore-and-recommend"; +import { hypothesisValidationFixture } from "../fixtures/planning-goals/hypothesis-validation"; +import { summarizePapersFixture } from "../fixtures/planning-goals/summarize-papers"; +import type { PlanningGoal } from "../schemas/planning-goal"; +import { validatePlan } from "../utils/plan-validator"; +import { analyzePlanTopology } from "../utils/topology-analyzer"; +import { generatePlan } from "./planner-agent"; const RUN_LLM_SCORERS = process.env.RUN_LLM_SCORERS === "true"; const describeIfLlm = RUN_LLM_SCORERS ? describe : describe.skip; @@ -33,7 +33,7 @@ if (!RUN_LLM_SCORERS) { /** * Helper to run a fixture through the planning pipeline and validate results. */ -async function runFixtureTest(fixture: PlanningFixture): Promise { +async function runFixtureTest(fixture: PlanningGoal): Promise { const { input, expected } = fixture; console.log(`\n${"=".repeat(60)}`); diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.ts b/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.ts deleted file mode 100644 index 710c2836c49..00000000000 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/fixtures.ts +++ /dev/null @@ -1,34 +0,0 @@ -/** - * Decomposition Prompts — Test Fixtures - * - * Exports all planning fixtures for use in tests and experiments. - * Fixtures are ordered by complexity (simplest first). - */ - -// Re-export types -export type { - ExpectedPlanCharacteristics, - PlanningFixture, - PlanningGoalInput, -} from "../../schemas/planning-fixture"; - -// Full complexity: Complete R&D cycle -export { ctDatabaseGoal, ctDatabaseGoalFixture } from "./ct-database-goal"; - -// Medium: Parallel research → evaluative synthesize -export { - exploreAndRecommendFixture, - exploreAndRecommendGoal, -} from "./explore-and-recommend"; - -// Complex: Research → experiment → synthesize (with hypotheses) -export { - hypothesisValidationFixture, - hypothesisValidationGoal, -} from "./hypothesis-validation"; - -// Simple: Linear research → synthesize -export { - summarizePapersFixture, - summarizePapersGoal, -} from "./summarize-papers"; diff --git a/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.bundled.json b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.bundled.json index 88f4d6b5538..ba18632b785 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.bundled.json +++ b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.bundled.json @@ -677,8 +677,8 @@ } }, "required": [ - "https://hash.ai/@h/types/property-type/shortname/", - "https://hash.ai/@h/types/property-type/organization-name/" + "https://hash.ai/@h/types/property-type/organization-name/", + "https://hash.ai/@h/types/property-type/shortname/" ], "title": "Organization", "type": "object" diff --git a/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.dereferenced.json b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.dereferenced.json index 4a3fdc93397..95369b81315 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.dereferenced.json +++ b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.dereferenced.json @@ -1155,8 +1155,8 @@ } }, "required": [ - "https://hash.ai/@h/types/property-type/shortname/", - "https://hash.ai/@h/types/property-type/organization-name/" + "https://hash.ai/@h/types/property-type/organization-name/", + "https://hash.ai/@h/types/property-type/shortname/" ], "title": "Organization", "type": "object" diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts b/apps/hash-ai-agent/src/mastra/fixtures/mock-plans.ts similarity index 99% rename from apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts rename to apps/hash-ai-agent/src/mastra/fixtures/mock-plans.ts index 5ff8792f97d..04d94a4542d 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/mock-plans.ts +++ b/apps/hash-ai-agent/src/mastra/fixtures/mock-plans.ts @@ -10,7 +10,7 @@ * Run with: npx tsx src/mastra/scripts/demo-plan-execution.ts --mock */ -import type { PlanSpec } from "../../schemas/plan-spec"; +import type { PlanSpec } from "../schemas/plan-spec"; // ============================================================================= // SUMMARIZE PAPERS (Simplest) diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/ct-database-goal.ts b/apps/hash-ai-agent/src/mastra/fixtures/planning-goals/ct-database-goal.ts similarity index 91% rename from apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/ct-database-goal.ts rename to apps/hash-ai-agent/src/mastra/fixtures/planning-goals/ct-database-goal.ts index a57a6441164..1fcfc2ca461 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/ct-database-goal.ts +++ b/apps/hash-ai-agent/src/mastra/fixtures/planning-goals/ct-database-goal.ts @@ -21,7 +21,7 @@ * - Should produce 8-15+ steps */ -import type { PlanningFixture } from "../../schemas/planning-fixture"; +import type { PlanningGoal } from "../../schemas/planning-goal"; /** * CT Database Goal fixture — the aspirational target. @@ -29,35 +29,35 @@ import type { PlanningFixture } from "../../schemas/planning-fixture"; * Goal: Create a category-theory native database. * Expected plan: Multi-phase R&D with research, experimentation, and development. */ -export const ctDatabaseGoalFixture: PlanningFixture = { +export const ctDatabaseGoalFixture: PlanningGoal = { input: { id: "ct-database-goal", - goal: `Create a backend language and database that is natively aligned - with category-theoretical expressions. This should support - objects, morphisms, functors, and natural transformations as - first-class concepts, with query performance competitive with + goal: `Create a backend language and database that is natively aligned + with category-theoretical expressions. This should support + objects, morphisms, functors, and natural transformations as + first-class concepts, with query performance competitive with traditional databases.`, - context: `We're exploring whether category theory (CT) primitives can - serve as a more natural foundation for data modeling than + context: `We're exploring whether category theory (CT) primitives can + serve as a more natural foundation for data modeling than relational or document models. - + Key unknowns: - Can CT concepts be efficiently indexed and queried? - What's the right level of abstraction for practical use? - How do we handle the impedance mismatch with existing systems? - Is there prior art we can build on? - - This is a long-term research project (6-12 months). We need + + This is a long-term research project (6-12 months). We need to validate feasibility before committing significant resources. - + The plan should include: 1. Literature review of CT in databases and programming languages 2. Feasibility experiments (can we represent and query CT structures?) 3. Performance benchmarking against traditional approaches 4. Prototype development if experiments are promising - - We're particularly interested in how functors could enable - schema migrations and how natural transformations could + + We're particularly interested in how functors could enable + schema migrations and how natural transformations could express data transformations.`, }, expected: { diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/explore-and-recommend.ts b/apps/hash-ai-agent/src/mastra/fixtures/planning-goals/explore-and-recommend.ts similarity index 92% rename from apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/explore-and-recommend.ts rename to apps/hash-ai-agent/src/mastra/fixtures/planning-goals/explore-and-recommend.ts index e5f8cd60ef6..52c934a9534 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/explore-and-recommend.ts +++ b/apps/hash-ai-agent/src/mastra/fixtures/planning-goals/explore-and-recommend.ts @@ -14,7 +14,7 @@ * - Should produce 4-8 steps */ -import type { PlanningFixture } from "../../schemas/planning-fixture"; +import type { PlanningGoal } from "../../schemas/planning-goal"; /** * Explore and Recommend fixture. @@ -22,15 +22,15 @@ import type { PlanningFixture } from "../../schemas/planning-fixture"; * Goal: Research vector database indexing approaches and recommend the best one. * Expected plan: Parallel research on different approaches → evaluative synthesize */ -export const exploreAndRecommendFixture: PlanningFixture = { +export const exploreAndRecommendFixture: PlanningGoal = { input: { id: "explore-and-recommend", - goal: `Research approaches to vector database indexing and recommend - the best approach for our use case: 10M documents, sub-100ms - query latency requirement, primarily similarity search with + goal: `Research approaches to vector database indexing and recommend + the best approach for our use case: 10M documents, sub-100ms + query latency requirement, primarily similarity search with occasional filtering.`, context: `We're evaluating vector databases for a semantic search feature. - Need to understand tradeoffs between HNSW, IVF, and other + Need to understand tradeoffs between HNSW, IVF, and other indexing approaches. The recommendation should consider: - Query latency at scale - Index build time diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/hypothesis-validation.ts b/apps/hash-ai-agent/src/mastra/fixtures/planning-goals/hypothesis-validation.ts similarity index 91% rename from apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/hypothesis-validation.ts rename to apps/hash-ai-agent/src/mastra/fixtures/planning-goals/hypothesis-validation.ts index b4f44066766..3428bc388c4 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/hypothesis-validation.ts +++ b/apps/hash-ai-agent/src/mastra/fixtures/planning-goals/hypothesis-validation.ts @@ -16,7 +16,7 @@ * - Should produce 5-10 steps */ -import type { PlanningFixture } from "../../schemas/planning-fixture"; +import type { PlanningGoal } from "../../schemas/planning-goal"; /** * Hypothesis Validation fixture. @@ -24,22 +24,22 @@ import type { PlanningFixture } from "../../schemas/planning-fixture"; * Goal: Test whether fine-tuning outperforms few-shot prompting for entity extraction. * Expected plan: Research → form hypothesis → design experiment → run → evaluate */ -export const hypothesisValidationFixture: PlanningFixture = { +export const hypothesisValidationFixture: PlanningGoal = { input: { id: "hypothesis-validation", - goal: `Test whether fine-tuning a small LLM (e.g., Llama 3 8B) on - domain-specific data outperforms few-shot prompting with a + goal: `Test whether fine-tuning a small LLM (e.g., Llama 3 8B) on + domain-specific data outperforms few-shot prompting with a larger model (e.g., GPT-4) for our entity extraction task.`, - context: `We have 5,000 labeled examples of entity extraction from - legal documents. Entities include: parties, dates, monetary + context: `We have 5,000 labeled examples of entity extraction from + legal documents. Entities include: parties, dates, monetary amounts, contract terms, and obligations. - + Key considerations: - Accuracy (F1 score) is the primary metric - Inference cost matters for production (processing ~10K docs/day) - We need to justify the choice to stakeholders - - The experiment should be rigorous enough to defend the + + The experiment should be rigorous enough to defend the recommendation. We suspect fine-tuning might win on accuracy but need to verify this hypothesis.`, }, diff --git a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/summarize-papers.ts b/apps/hash-ai-agent/src/mastra/fixtures/planning-goals/summarize-papers.ts similarity index 89% rename from apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/summarize-papers.ts rename to apps/hash-ai-agent/src/mastra/fixtures/planning-goals/summarize-papers.ts index 74b3262c7a1..9a304572328 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/decomposition-prompts/summarize-papers.ts +++ b/apps/hash-ai-agent/src/mastra/fixtures/planning-goals/summarize-papers.ts @@ -12,7 +12,7 @@ * - Should produce 3-6 steps */ -import type { PlanningFixture } from "../../schemas/planning-fixture"; +import type { PlanningGoal } from "../../schemas/planning-goal"; /** * Summarize Papers fixture — the simplest planning goal. @@ -20,14 +20,14 @@ import type { PlanningFixture } from "../../schemas/planning-fixture"; * Goal: Summarize 3 papers on RAG and produce a comparison table. * Expected plan: Parallel research → synthesize */ -export const summarizePapersFixture: PlanningFixture = { +export const summarizePapersFixture: PlanningGoal = { input: { id: "summarize-papers", - goal: `Summarize 3 recent papers on retrieval-augmented generation (RAG) + goal: `Summarize 3 recent papers on retrieval-augmented generation (RAG) and produce a comparison table of their approaches.`, - context: `We need to understand the current landscape of RAG techniques + context: `We need to understand the current landscape of RAG techniques for an internal tech review. Focus on papers from the last 2 years. - The comparison should cover: architecture, retrieval method, + The comparison should cover: architecture, retrieval method, performance claims, and limitations.`, }, expected: { diff --git a/apps/hash-ai-agent/src/mastra/schemas/planning-fixture.ts b/apps/hash-ai-agent/src/mastra/schemas/planning-goal.ts similarity index 97% rename from apps/hash-ai-agent/src/mastra/schemas/planning-fixture.ts rename to apps/hash-ai-agent/src/mastra/schemas/planning-goal.ts index 51dba4425d4..5683d4410b4 100644 --- a/apps/hash-ai-agent/src/mastra/schemas/planning-fixture.ts +++ b/apps/hash-ai-agent/src/mastra/schemas/planning-goal.ts @@ -41,7 +41,7 @@ export interface ExpectedPlanCharacteristics { /** * A complete planning fixture with input and expected characteristics. */ -export interface PlanningFixture { +export interface PlanningGoal { input: PlanningGoalInput; expected: ExpectedPlanCharacteristics; } diff --git a/apps/hash-ai-agent/src/mastra/scripts/generate-schemas.ts b/apps/hash-ai-agent/src/mastra/scripts/generate-schemas.ts index c4546588937..173cdb00832 100644 --- a/apps/hash-ai-agent/src/mastra/scripts/generate-schemas.ts +++ b/apps/hash-ai-agent/src/mastra/scripts/generate-schemas.ts @@ -20,7 +20,7 @@ * other use cases (standard JSON Schema validators, etc.). * * Usage: - * tsx apps/hash-ai-agent/src/mastra/fixtures/generate-schemas.ts + * tsx apps/hash-ai-agent/src/mastra/scripts/generate-schemas.ts * * Or via npm script: * yarn workspace @apps/hash-ai-agent generate-schemas @@ -193,7 +193,7 @@ function normalizeToDefsStructure( } async function generateSchemas() { - const outputDir = path.join(__dirname, "entity-schemas"); + const outputDir = path.join(__dirname, "../fixtures/entity-schemas"); await mkdir(outputDir, { recursive: true }); diff --git a/apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts b/apps/hash-ai-agent/src/mastra/scripts/planning-workflow-mock-demo.ts similarity index 97% rename from apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts rename to apps/hash-ai-agent/src/mastra/scripts/planning-workflow-mock-demo.ts index a6046061ee0..ee8df19dc97 100644 --- a/apps/hash-ai-agent/src/mastra/scripts/demo-plan-execution.ts +++ b/apps/hash-ai-agent/src/mastra/scripts/planning-workflow-mock-demo.ts @@ -21,20 +21,18 @@ import * as p from "@clack/prompts"; import color from "picocolors"; -import { - ctDatabaseGoalFixture, - exploreAndRecommendFixture, - hypothesisValidationFixture, - type PlanningFixture, - summarizePapersFixture, -} from "../fixtures/decomposition-prompts/fixtures"; -import { getMockPlan } from "../fixtures/decomposition-prompts/mock-plans"; +import { getMockPlan } from "../fixtures/mock-plans"; +import { ctDatabaseGoalFixture } from "../fixtures/planning-goals/ct-database-goal"; +import { exploreAndRecommendFixture } from "../fixtures/planning-goals/explore-and-recommend"; +import { hypothesisValidationFixture } from "../fixtures/planning-goals/hypothesis-validation"; +import { summarizePapersFixture } from "../fixtures/planning-goals/summarize-papers"; import type { Executor, PlanSpec, PlanStep, StepType, } from "../schemas/plan-spec"; +import type { PlanningGoal } from "../schemas/planning-goal"; import { compilePlanToWorkflow, type PlanExecutionEvent, @@ -49,7 +47,7 @@ import { planningWorkflow } from "../workflows/planning-workflow"; * All available fixtures with display metadata. */ const FIXTURES: Array<{ - fixture: PlanningFixture; + fixture: PlanningGoal; label: string; hint: string; }> = [ @@ -283,7 +281,7 @@ function displayPlanVisualization(plan: PlanSpec): void { * In mock mode, returns the cached plan. Otherwise, uses the LLM. */ async function generatePlanFromFixture( - fixture: PlanningFixture, + fixture: PlanningGoal, useMock: boolean, spinner: ReturnType, ): Promise<{ plan: PlanSpec; fromCache: boolean }> { @@ -497,7 +495,7 @@ async function executePlan( */ async function runDemoIteration(cliArgs: CliArgs): Promise { // Fixture selection - use CLI arg or prompt - let selectedFixture: PlanningFixture; + let selectedFixture: PlanningGoal; if (cliArgs.fixture) { const found = FIXTURES.find( diff --git a/apps/hash-ai-agent/src/mastra/workflows/planning-workflow.test.ts b/apps/hash-ai-agent/src/mastra/workflows/planning-workflow.test.ts index bee7dbd3828..a755f773a53 100644 --- a/apps/hash-ai-agent/src/mastra/workflows/planning-workflow.test.ts +++ b/apps/hash-ai-agent/src/mastra/workflows/planning-workflow.test.ts @@ -1,34 +1,13 @@ /* eslint-disable no-console */ /** - * Planning Pipeline E2E Tests + * Planning Workflow Tests * - * Tests the full planning pipeline: - * Goal → Planner Agent → PlanSpec → Validator → Scorers - * - * Runs all 4 fixtures through the pipeline and collects results for analysis. - * This surfaces any schema/output mismatches before building the revision workflow. + * Focused on the revision loop behavior (goal → plan → validate → revise). + * Keeps fixtures-based planner testing in the planner agent suite. */ import { describe, expect, test } from "vitest"; -import { generatePlan } from "../agents/planner-agent"; -import { - ctDatabaseGoalFixture, - exploreAndRecommendFixture, - hypothesisValidationFixture, - type PlanningFixture, - summarizePapersFixture, -} from "../fixtures/decomposition-prompts/fixtures"; -import type { PlanSpec } from "../schemas/plan-spec"; -import { - type CompositePlanScore, - scorePlanComposite, -} from "../scorers/plan-scorers"; -import { validatePlan, type ValidationResult } from "../utils/plan-validator"; -import { - analyzePlanTopology, - type TopologyAnalysis, -} from "../utils/topology-analyzer"; import { planningWorkflow } from "./planning-workflow"; // ============================================================================= @@ -36,52 +15,17 @@ import { planningWorkflow } from "./planning-workflow"; // ============================================================================= /** - * Set RUN_LLM_SCORERS=true to run LLM-based scorers (slower, costs API credits) + * Set RUN_LLM_SCORERS=true to run these LLM-dependent tests. */ const RUN_LLM_SCORERS = process.env.RUN_LLM_SCORERS === "true"; const describeIfLlm = RUN_LLM_SCORERS ? describe : describe.skip; if (!RUN_LLM_SCORERS) { console.warn( - "Skipping planning pipeline E2E tests; set RUN_LLM_SCORERS=true or run `yarn eval`.", + "Skipping planning workflow tests; set RUN_LLM_SCORERS=true to enable.", ); } -/** - * All fixtures ordered by complexity (simplest first) - */ -const ALL_FIXTURES: PlanningFixture[] = [ - summarizePapersFixture, - exploreAndRecommendFixture, - hypothesisValidationFixture, - ctDatabaseGoalFixture, -]; - -// ============================================================================= -// RESULT TYPES -// ============================================================================= - -interface LlmScoreResult { - score: number; - reason: string; -} - -interface PipelineResult { - fixtureId: string; - success: boolean; - plan?: PlanSpec; - validation?: ValidationResult; - topology?: TopologyAnalysis; - deterministicScores?: CompositePlanScore; - llmScores?: { - goalAlignment?: LlmScoreResult; - granularity?: LlmScoreResult; - testability?: LlmScoreResult; - }; - error?: string; - durationMs: number; -} - // ============================================================================= // HELPERS // ============================================================================= @@ -92,398 +36,25 @@ function logSectionHeader(title: string): void { console.log("=".repeat(60)); } -function logSubsection(title: string): void { - console.log(`\n--- ${title} ---`); -} - -function logPlanSummary(plan: PlanSpec): void { - console.log(` ID: ${plan.id}`); - console.log(` Goal Summary: ${plan.goalSummary.slice(0, 80)}...`); - console.log(` Steps: ${plan.steps.length}`); - console.log(` Requirements: ${plan.requirements.length}`); - console.log(` Hypotheses: ${plan.hypotheses.length}`); - - const stepTypes = plan.steps.map((step) => step.type); - const typeCounts = stepTypes.reduce( - (acc, type) => { - acc[type] = (acc[type] ?? 0) + 1; - return acc; - }, - {} as Record, - ); - console.log(` Step types: ${JSON.stringify(typeCounts)}`); -} - -function logValidation(validation: ValidationResult): void { - console.log(` Valid: ${validation.valid}`); - console.log(` Errors: ${validation.errors.length}`); - if (!validation.valid) { - for (const error of validation.errors.slice(0, 5)) { - console.log(` [${error.code}] ${error.message}`); - } - if (validation.errors.length > 5) { - console.log(` ... and ${validation.errors.length - 5} more`); - } - } -} - -function logTopology(topology: TopologyAnalysis): void { - console.log(` Entry points: [${topology.entryPoints.join(", ")}]`); - console.log(` Exit points: [${topology.exitPoints.join(", ")}]`); - console.log(` Critical path: ${topology.criticalPath.length} steps`); - console.log(` Parallel groups: ${topology.parallelGroups.length}`); -} - -function logDeterministicScores(scores: CompositePlanScore): void { - console.log(` Overall: ${(scores.overall * 100).toFixed(1)}%`); - console.log(` Structure: ${(scores.structure.score * 100).toFixed(1)}%`); - console.log(` Coverage: ${(scores.coverage.score * 100).toFixed(1)}%`); - console.log( - ` Experiment Rigor: ${(scores.experimentRigor.score * 100).toFixed(1)}%`, - ); - console.log( - ` Unknowns Coverage: ${(scores.unknownsCoverage.score * 100).toFixed(1)}%`, - ); -} - -function checkExpectedCharacteristics( - plan: PlanSpec, - fixture: PlanningFixture, -): string[] { - const issues: string[] = []; - const { expected } = fixture; - - // Check step count - if (plan.steps.length < expected.minSteps) { - issues.push(`Too few steps: ${plan.steps.length} < ${expected.minSteps}`); - } - if (expected.maxSteps && plan.steps.length > expected.maxSteps) { - issues.push(`Too many steps: ${plan.steps.length} > ${expected.maxSteps}`); - } - - // Check hypotheses - const hasHypotheses = plan.hypotheses.length > 0; - if (expected.shouldHaveHypotheses && !hasHypotheses) { - issues.push("Expected hypotheses but found none"); - } - if (!expected.shouldHaveHypotheses && hasHypotheses) { - issues.push(`Unexpected hypotheses: ${plan.hypotheses.length}`); - } - - // Check experiments - const experimentSteps = plan.steps.filter( - (step) => step.type === "experiment", - ); - if (expected.shouldHaveExperiments && experimentSteps.length === 0) { - issues.push("Expected experiment steps but found none"); - } - if (!expected.shouldHaveExperiments && experimentSteps.length > 0) { - issues.push(`Unexpected experiment steps: ${experimentSteps.length}`); - } - - // Check step types - const actualTypes = new Set(plan.steps.map((step) => step.type)); - for (const expectedType of expected.expectedStepTypes) { - if (!actualTypes.has(expectedType)) { - issues.push(`Missing expected step type: ${expectedType}`); - } - } - - return issues; -} - -// ============================================================================= -// LLM SCORER RUNNER -// ============================================================================= - -async function runLlmScorers( - fixture: PlanningFixture, - plan: PlanSpec, -): Promise> { - // Dynamic import to avoid loading if not needed - const { - goalAlignmentScorer, - planGranularityScorer, - hypothesisTestabilityScorer, - } = await import("../scorers/plan-llm-scorers"); - - const scorerInput = { goal: fixture.input.goal, plan }; - const scorerOutput = { text: JSON.stringify(plan) }; - const results: NonNullable = {}; - - try { - const alignmentResult = await goalAlignmentScorer.run({ - input: scorerInput, - output: scorerOutput, - }); - results.goalAlignment = { - score: alignmentResult.score, - reason: alignmentResult.reason ?? "", - }; - } catch (error) { - console.error(` Goal alignment scorer failed: ${String(error)}`); - } - - try { - const granularityResult = await planGranularityScorer.run({ - input: scorerInput, - output: scorerOutput, - }); - results.granularity = { - score: granularityResult.score, - reason: granularityResult.reason ?? "", - }; - } catch (error) { - console.error(` Granularity scorer failed: ${String(error)}`); - } - - try { - const testabilityResult = await hypothesisTestabilityScorer.run({ - input: scorerInput, - output: scorerOutput, - }); - results.testability = { - score: testabilityResult.score, - reason: testabilityResult.reason ?? "", - }; - } catch (error) { - console.error(` Testability scorer failed: ${String(error)}`); - } - - return results; -} - -// ============================================================================= -// MAIN TEST RUNNER -// ============================================================================= - -async function runPipelineForFixture( - fixture: PlanningFixture, -): Promise { - const startTime = Date.now(); - const result: PipelineResult = { - fixtureId: fixture.input.id, - success: false, - durationMs: 0, - }; - - try { - // Step 1: Generate plan - logSubsection("Generating Plan"); - const genResult = await generatePlan({ - goal: fixture.input.goal, - context: fixture.input.context, - }); - result.plan = genResult.plan; - logPlanSummary(genResult.plan); - - // Step 2: Validate plan - logSubsection("Validation"); - result.validation = validatePlan(genResult.plan); - logValidation(result.validation); - - if (!result.validation.valid) { - result.error = `Validation failed: ${result.validation.errors[0]?.message}`; - result.durationMs = Date.now() - startTime; - return result; - } - - // Step 3: Analyze topology - logSubsection("Topology Analysis"); - result.topology = analyzePlanTopology(genResult.plan); - logTopology(result.topology); - - // Step 4: Run deterministic scorers - logSubsection("Deterministic Scores"); - result.deterministicScores = scorePlanComposite(genResult.plan); - logDeterministicScores(result.deterministicScores); - - // Step 5: Check expected characteristics - logSubsection("Expected Characteristics Check"); - const charIssues = checkExpectedCharacteristics(genResult.plan, fixture); - if (charIssues.length > 0) { - console.log(" Issues:"); - for (const issue of charIssues) { - console.log(` ⚠️ ${issue}`); - } - } else { - console.log(" ✅ All expected characteristics met"); - } - - // Step 6: Run LLM scorers (if enabled) - if (RUN_LLM_SCORERS) { - logSubsection("LLM Scores"); - const llmScores = await runLlmScorers(fixture, genResult.plan); - result.llmScores = llmScores; - if (llmScores.goalAlignment) { - console.log( - ` Goal Alignment: ${(llmScores.goalAlignment.score * 100).toFixed(1)}%`, - ); - } - if (llmScores.granularity) { - console.log( - ` Granularity: ${(llmScores.granularity.score * 100).toFixed(1)}%`, - ); - } - if (llmScores.testability) { - console.log( - ` Testability: ${(llmScores.testability.score * 100).toFixed(1)}%`, - ); - } - } else { - console.log( - "\n (LLM scorers skipped — set RUN_LLM_SCORERS=true to enable)", - ); - } - - result.success = true; - } catch (error) { - result.error = error instanceof Error ? error.message : String(error); - console.error(`\n ❌ Error: ${result.error}`); - } - - result.durationMs = Date.now() - startTime; - return result; -} - // ============================================================================= // TESTS // ============================================================================= -describeIfLlm("Planning Pipeline E2E", () => { - // Timeout for LLM calls: 2 minutes per fixture - const FIXTURE_TIMEOUT = 2 * 60 * 1000; - - describe("Individual Fixtures", () => { - test.each(ALL_FIXTURES)( - "generates valid plan for: $input.id", - async (fixture) => { - logSectionHeader(`FIXTURE: ${fixture.input.id}`); - console.log(`Goal: ${fixture.input.goal.slice(0, 100)}...`); - - const result = await runPipelineForFixture(fixture); - - console.log(`\n Duration: ${(result.durationMs / 1000).toFixed(1)}s`); - - // Assertions - expect(result.plan).toBeDefined(); - expect(result.validation?.valid).toBe(true); - expect(result.plan?.steps.length).toBeGreaterThan(0); - - // Check minimum expected step types are present - const actualTypes = new Set( - result.plan?.steps.map((step) => step.type) ?? [], - ); - for (const expectedType of fixture.expected.expectedStepTypes) { - expect(actualTypes.has(expectedType)).toBe(true); - } - }, - FIXTURE_TIMEOUT, - ); - }); - - describe("Summary Report", () => { - test( - "runs all fixtures and generates summary", - async () => { - logSectionHeader("RUNNING ALL FIXTURES"); - - const results: PipelineResult[] = []; - - for (const fixture of ALL_FIXTURES) { - logSectionHeader(`FIXTURE: ${fixture.input.id}`); - console.log(`Goal: ${fixture.input.goal.slice(0, 100)}...`); - - const result = await runPipelineForFixture(fixture); - results.push(result); - - console.log( - `\n Duration: ${(result.durationMs / 1000).toFixed(1)}s`, - ); - console.log( - ` Result: ${result.success ? "✅ SUCCESS" : "❌ FAILED"}`, - ); - } - - // Generate summary - logSectionHeader("SUMMARY REPORT"); - - const successful = results.filter((res) => res.success); - const failed = results.filter((res) => !res.success); - - console.log(`\nTotal: ${results.length} fixtures`); - console.log(`Successful: ${successful.length}`); - console.log(`Failed: ${failed.length}`); - - if (failed.length > 0) { - console.log("\nFailures:"); - for (const result of failed) { - console.log(` - ${result.fixtureId}: ${result.error}`); - } - } - - // Score summary for successful plans - if (successful.length > 0) { - console.log("\nDeterministic Scores:"); - console.log( - " Fixture | Overall | Structure | Coverage | Rigor | Unknowns", - ); - console.log(` ${"-".repeat(85)}`); - - for (const result of successful) { - if (result.deterministicScores) { - const scores = result.deterministicScores; - const row = [ - result.fixtureId.padEnd(28), - `${(scores.overall * 100).toFixed(0)}%`.padStart(7), - `${(scores.structure.score * 100).toFixed(0)}%`.padStart(9), - `${(scores.coverage.score * 100).toFixed(0)}%`.padStart(8), - `${(scores.experimentRigor.score * 100).toFixed(0)}%`.padStart( - 5, - ), - `${(scores.unknownsCoverage.score * 100).toFixed(0)}%`.padStart( - 8, - ), - ]; - console.log(` ${row.join(" | ")}`); - } - } - } - - // Total duration - const totalDuration = results.reduce( - (sum, res) => sum + res.durationMs, - 0, - ); - console.log(`\nTotal duration: ${(totalDuration / 1000).toFixed(1)}s`); - - // Expect at least some success - expect(successful.length).toBeGreaterThan(0); - }, - ALL_FIXTURES.length * FIXTURE_TIMEOUT, - ); - }); -}); - -// ============================================================================= -// REVISION WORKFLOW TESTS -// ============================================================================= - describeIfLlm("Planning Workflow with Revision Loop", () => { - // Timeout for workflow with potential revisions: 4 minutes const WORKFLOW_TIMEOUT = 4 * 60 * 1000; test( - "ct-database-goal passes after revision", + "returns a valid plan within maxAttempts", async () => { - logSectionHeader("REVISION WORKFLOW: ct-database-goal"); - console.log(`Goal: ${ctDatabaseGoalFixture.input.goal.slice(0, 100)}...`); + logSectionHeader("REVISION WORKFLOW: simple goal"); + const goal = "Summarize three recent RAG papers for an internal review."; + const context = "Focus on architecture and evaluation methodology."; const run = await planningWorkflow.createRun(); const result = await run.start({ inputData: { - goal: ctDatabaseGoalFixture.input.goal, - context: ctDatabaseGoalFixture.input.context, + goal, + context, maxAttempts: 3, }, }); @@ -491,7 +62,6 @@ describeIfLlm("Planning Workflow with Revision Loop", () => { console.log("\n=== Workflow Result ==="); console.log(` Status: ${result.status}`); - // Assert workflow completed successfully expect(result.status).toBe("success"); if (result.status === "success") { @@ -500,14 +70,6 @@ describeIfLlm("Planning Workflow with Revision Loop", () => { console.log(` Attempts: ${output.attempts}`); console.log(` Plan steps: ${output.plan.steps.length}`); - if (output.errors && output.errors.length > 0) { - console.log(` Errors: ${output.errors.length}`); - for (const error of output.errors.slice(0, 3)) { - console.log(` - [${error.code}] ${error.message}`); - } - } - - // Assertions expect(output.valid).toBe(true); expect(output.attempts).toBeLessThanOrEqual(3); expect(output.plan.steps.length).toBeGreaterThan(0); @@ -517,135 +79,35 @@ describeIfLlm("Planning Workflow with Revision Loop", () => { ); test( - "simple fixture passes on first attempt", + "respects maxAttempts", async () => { - logSectionHeader("REVISION WORKFLOW: summarize-papers"); - console.log( - `Goal: ${summarizePapersFixture.input.goal.slice(0, 100)}...`, - ); + logSectionHeader("REVISION WORKFLOW: maxAttempts"); + const goal = "Design an experiment to compare two retrieval methods."; + const context = "Include confirmatory vs exploratory considerations."; const run = await planningWorkflow.createRun(); const result = await run.start({ inputData: { - goal: summarizePapersFixture.input.goal, - context: summarizePapersFixture.input.context, - maxAttempts: 3, + goal, + context, + maxAttempts: 1, }, }); console.log("\n=== Workflow Result ==="); console.log(` Status: ${result.status}`); + expect(result.status).toBe("success"); + if (result.status === "success") { const output = result.result; console.log(` Valid: ${output.valid}`); console.log(` Attempts: ${output.attempts}`); console.log(` Plan steps: ${output.plan.steps.length}`); - // Simple fixture should pass on first attempt - expect(output.valid).toBe(true); expect(output.attempts).toBe(1); - } else { - expect(result.status).toBe("success"); } }, WORKFLOW_TIMEOUT, ); - - test( - "runs all fixtures through revision workflow", - async () => { - logSectionHeader("REVISION WORKFLOW: All Fixtures"); - - interface WorkflowResult { - fixtureId: string; - valid: boolean; - attempts: number; - stepCount: number; - errors?: Array<{ code: string; message: string }>; - durationMs: number; - } - - const results: WorkflowResult[] = []; - - for (const fixture of ALL_FIXTURES) { - console.log(`\n--- ${fixture.input.id} ---`); - const startTime = Date.now(); - - const run = await planningWorkflow.createRun(); - const result = await run.start({ - inputData: { - goal: fixture.input.goal, - context: fixture.input.context, - maxAttempts: 3, - }, - }); - - const durationMs = Date.now() - startTime; - - if (result.status === "success") { - const output = result.result; - results.push({ - fixtureId: fixture.input.id, - valid: output.valid, - attempts: output.attempts, - stepCount: output.plan.steps.length, - errors: output.errors?.map((err) => ({ - code: String(err.code), - message: err.message, - })), - durationMs, - }); - console.log( - ` Valid: ${output.valid}, Attempts: ${output.attempts}, Steps: ${ - output.plan.steps.length - }, Duration: ${(durationMs / 1000).toFixed(1)}s`, - ); - } else { - results.push({ - fixtureId: fixture.input.id, - valid: false, - attempts: 0, - stepCount: 0, - errors: [ - { code: "WORKFLOW_FAILED", message: "Workflow did not complete" }, - ], - durationMs, - }); - console.log(` FAILED: Workflow did not complete`); - } - } - - // Summary - logSectionHeader("REVISION WORKFLOW SUMMARY"); - console.log( - "\n Fixture | Valid | Attempts | Steps | Duration", - ); - console.log(` ${"-".repeat(70)}`); - - for (const result of results) { - const row = [ - result.fixtureId.padEnd(28), - (result.valid ? "YES" : "NO").padStart(5), - String(result.attempts).padStart(8), - String(result.stepCount).padStart(5), - `${(result.durationMs / 1000).toFixed(1)}s`.padStart(8), - ]; - console.log(` ${row.join(" | ")}`); - } - - const totalDuration = results.reduce( - (sum, res) => sum + res.durationMs, - 0, - ); - const validCount = results.filter((res) => res.valid).length; - console.log( - `\n Total: ${validCount}/${results.length} valid, ${(totalDuration / 1000).toFixed(1)}s`, - ); - - // All fixtures should eventually pass - expect(validCount).toBe(results.length); - }, - ALL_FIXTURES.length * WORKFLOW_TIMEOUT, - ); }); From 8db044d62135e96793900838d86876f9f1e046d0 Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 22 Dec 2025 15:27:18 +0100 Subject: [PATCH 13/16] modify the mock-planning-demo --- ...low-mock-demo.ts => mock-planning-demo.ts} | 59 +++++++++++-------- 1 file changed, 33 insertions(+), 26 deletions(-) rename apps/hash-ai-agent/src/mastra/scripts/{planning-workflow-mock-demo.ts => mock-planning-demo.ts} (96%) diff --git a/apps/hash-ai-agent/src/mastra/scripts/planning-workflow-mock-demo.ts b/apps/hash-ai-agent/src/mastra/scripts/mock-planning-demo.ts similarity index 96% rename from apps/hash-ai-agent/src/mastra/scripts/planning-workflow-mock-demo.ts rename to apps/hash-ai-agent/src/mastra/scripts/mock-planning-demo.ts index ee8df19dc97..4de51d85586 100644 --- a/apps/hash-ai-agent/src/mastra/scripts/planning-workflow-mock-demo.ts +++ b/apps/hash-ai-agent/src/mastra/scripts/mock-planning-demo.ts @@ -532,32 +532,6 @@ async function runDemoIteration(cliArgs: CliArgs): Promise { )!.fixture; } - // Delay selection - use CLI arg, --fast flag, or prompt - let delayMs: number; - - if (cliArgs.fast) { - delayMs = 100; - p.log.info(`Mock agent delay: ${color.cyan("100ms")} (--fast mode)`); - } else if (cliArgs.delay !== undefined) { - delayMs = cliArgs.delay; - p.log.info(`Mock agent delay: ${color.cyan(String(delayMs))}ms (from CLI)`); - } else { - const delayChoice = await p.select({ - message: "Select mock agent delay:", - options: [ - { value: 1000, label: "Normal (1s)", hint: "Comfortable pace" }, - { value: 2000, label: "Slow (2s)", hint: "Easy to follow" }, - { value: 3000, label: "Very slow (3s)", hint: "Step by step" }, - ], - }); - - if (p.isCancel(delayChoice)) { - return false; - } - - delayMs = delayChoice as number; - } - // Display goal p.log.step("Goal:"); p.log.message(color.dim(selectedFixture.input.goal.trim())); @@ -610,6 +584,39 @@ async function runDemoIteration(cliArgs: CliArgs): Promise { ); } + // Ask whether to execute and select delay + let delayMs: number; + if (cliArgs.fast) { + delayMs = 100; + p.log.info(`Mock agent delay: ${color.cyan("100ms")} (--fast mode)`); + } else if (cliArgs.delay !== undefined) { + delayMs = cliArgs.delay; + p.log.info(`Mock agent delay: ${color.cyan(String(delayMs))}ms (from CLI)`); + } else { + const executeChoice = await p.select({ + message: "Execute this plan now?", + options: [ + { value: 1000, label: "Yes — Normal (1s)", hint: "Comfortable pace" }, + { value: 2000, label: "Yes — Slow (2s)", hint: "Easy to follow" }, + { value: 3000, label: "Yes — Very slow (3s)", hint: "Step by step" }, + { value: "__back__", label: "No — pick another goal", hint: "Back" }, + { value: "__exit__", label: "No — exit demo", hint: "Quit" }, + ], + }); + + const selection = executeChoice as number | "__back__" | "__exit__"; + + if (p.isCancel(executeChoice) || selection === "__exit__") { + return false; + } + + if (selection === "__back__") { + return !cliArgs.fixture; + } + + delayMs = selection; + } + // Brief pause before execution await delay(500); From ac174987969402705a4db59ad8a091f645931d2a Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 22 Dec 2025 15:57:01 +0100 Subject: [PATCH 14/16] add a simple frontend client based on ui-dojo examples --- .../_ai/wiki/deployment-requirements.md | 120 ++ .../_ai/wiki/gaps-and-next-steps.md | 8 + apps/hash-ai-agent/package.json | 28 +- apps/hash-ai-agent/src/client/README.md | 188 +++ apps/hash-ai-agent/src/client/app.tsx | 53 + .../src/client/components/chat.tsx | 249 ++++ apps/hash-ai-agent/src/client/index.html | 28 + apps/hash-ai-agent/src/client/main.tsx | 16 + apps/hash-ai-agent/src/client/tsconfig.json | 17 + apps/hash-ai-agent/src/client/vite.config.ts | 32 + apps/hash-ai-agent/src/mastra/index.ts | 30 + apps/hash-ai-agent/tsconfig.json | 1 + yarn.lock | 1218 +++++++++++++++-- 13 files changed, 1832 insertions(+), 156 deletions(-) create mode 100644 apps/hash-ai-agent/_ai/wiki/deployment-requirements.md create mode 100644 apps/hash-ai-agent/src/client/README.md create mode 100644 apps/hash-ai-agent/src/client/app.tsx create mode 100644 apps/hash-ai-agent/src/client/components/chat.tsx create mode 100644 apps/hash-ai-agent/src/client/index.html create mode 100644 apps/hash-ai-agent/src/client/main.tsx create mode 100644 apps/hash-ai-agent/src/client/tsconfig.json create mode 100644 apps/hash-ai-agent/src/client/vite.config.ts diff --git a/apps/hash-ai-agent/_ai/wiki/deployment-requirements.md b/apps/hash-ai-agent/_ai/wiki/deployment-requirements.md new file mode 100644 index 00000000000..369e1796934 --- /dev/null +++ b/apps/hash-ai-agent/_ai/wiki/deployment-requirements.md @@ -0,0 +1,120 @@ +# Deployment Requirements: Mastra Workflow State Management + +> Technical requirements for deploying human-in-the-loop workflows with Mastra. +> Captured 2024-12-22. Source: Analysis of Mastra core (vNext/Evented model). + +## Key Finding: Storage is Required for Human-in-the-Loop + +**In-memory state is sufficient for single-run workflows**, but **storage is essential for suspend/resume across execution sessions**. + +### Why This Matters + +- **Single-run workflow**: Steps pass outputs in-memory via accumulated `stepResults` object. No database involved. +- **Human-in-the-loop workflow**: Step calls `suspend()`, workflow state persists to storage, process can terminate. Hours/days later, `resume()` loads state from storage and continues. + +Without storage configured, suspended workflows lose all state on process restart. + +## Storage Requirements by Use Case + +| Use Case | Storage Required? | +|----------|-------------------| +| Workflows completing in single execution | No | +| Human approval gates | **Yes** | +| Long-running workflows (survive restarts) | **Yes** | +| External webhook callbacks | **Yes** | +| Audit trail / workflow history queries | **Yes** | + +## Configuring Storage + +```typescript +import { Mastra } from "@mastra/core"; +import { PostgresStore } from "@mastra/pg"; + +const mastra = new Mastra({ + storage: new PostgresStore({ + connectionString: process.env.DATABASE_URL + }) +}); +``` + +### Supported Backends +- **PostgreSQL** - production recommended +- **LibSQL/SQLite** - local development, serverless edge +- **Custom** - implement `BaseStorage` interface + +## Suspend/Resume Pattern + +### Suspending a Workflow + +```typescript +const approvalStep = createStep({ + id: "request-approval", + inputSchema: z.object({ proposal: z.string() }), + suspendSchema: z.object({ + reason: z.string(), + context: z.record(z.unknown()) + }), + resumeSchema: z.object({ + approved: z.boolean(), + notes: z.string().optional() + }), + execute: async ({ inputData, resumeData, suspend }) => { + // If not yet approved, suspend and wait + if (!resumeData?.approved) { + await suspend({ + reason: "Human approval required", + context: { proposal: inputData.proposal } + }); + return; // Execution stops here + } + + // Resumed with approval + return { approved: true, notes: resumeData.notes }; + } +}); +``` + +### Resuming a Workflow + +```typescript +// Later, when human approves via API/UI: +const run = await workflow.getRunById(runId); +const result = await run.resume({ + resumeData: { approved: true, notes: "LGTM" } +}); +``` + +### Querying Suspended Workflows + +```typescript +// Find workflows awaiting human input +const pending = await mastra.getStorage().getWorkflowRuns({ + workflowName: "approval-workflow", + status: "suspended" +}); +``` + +## vNext (Evented) Model + +The evented execution model treats suspend/resume as first-class workflow states: + +- **Suspend** publishes `workflow.suspend` event, persists snapshot +- **Resume** publishes `workflow.resume` event, loads snapshot, continues from `suspendedPaths` +- **External systems** can subscribe to events for notifications + +This model is cleaner for human-in-the-loop because state transitions are explicit events rather than implicit control flow. + +## Implementation Checklist + +1. **Configure storage backend** (PostgreSQL for production) +2. **Define `suspendSchema`** - what context surfaces to human reviewer +3. **Define `resumeSchema`** - validate human input on resume +4. **Build resume trigger** - API endpoint or UI action +5. **Handle edge cases** - abandoned workflows, failed resumes, timeouts + +## Open Questions + +1. **Storage backend**: PostgreSQL vs LibSQL for our deployment? +2. **Resume mechanism**: API endpoint, UI component, or event subscription? +3. **Suspend payload design**: What information do human reviewers need? +4. **Workflow lifecycle**: How to handle abandoned/expired suspended workflows? diff --git a/apps/hash-ai-agent/_ai/wiki/gaps-and-next-steps.md b/apps/hash-ai-agent/_ai/wiki/gaps-and-next-steps.md index aca40091caf..1d1d340af31 100644 --- a/apps/hash-ai-agent/_ai/wiki/gaps-and-next-steps.md +++ b/apps/hash-ai-agent/_ai/wiki/gaps-and-next-steps.md @@ -33,6 +33,14 @@ These represent a shift toward **epistemically rigorous R&D orchestration** rath --- +## Recent Observations (2025-05-04) + +- **Branching + suspend/resume** need to be first-class in the compiler approach. We should plan for conditional paths and HITL pauses as part of the compiled workflow model, not just at the prompt layer. +- **Error handling needs a policy layer**: beyond fail-fast, we need declarative choices for retries, fallbacks, and “continue-on-error” semantics. This should be modeled separately from step logic (e.g., per-step or per-plan execution policy). +- **Mastra dev UI is useful but limited** for interaction patterns; keep the TUI demo path as the primary interactive surface until a dedicated frontend is warranted. + +--- + ## Priority 1: Handoff Packet Integration **Problem**: Current step outputs are unstructured (`outputs: DataContract[]` at plan-time, arbitrary objects at runtime). No standard for what constitutes a "complete" step contribution. diff --git a/apps/hash-ai-agent/package.json b/apps/hash-ai-agent/package.json index d998a80684c..4596dc5c92e 100644 --- a/apps/hash-ai-agent/package.json +++ b/apps/hash-ai-agent/package.json @@ -10,7 +10,9 @@ "build": "mastra build", "codegen": "tsx src/mastra/fixtures/generate-schemas.ts", "demo:plan": "tsx src/mastra/scripts/demo-plan-execution.ts", - "dev": "mastra dev", + "dev": "concurrently --names mastra,client --prefix-colors blue,green \"yarn dev:mastra\" \"yarn dev:client\"", + "dev:mastra": "mastra dev", + "dev:client": "vite --config src/client/vite.config.ts", "eval": "RUN_LLM_SCORERS=true vitest run", "eval:dev": "RUN_LLM_SCORERS=true vitest dev", "fix": "npm-run-all --continue-on-error \"fix:*\"", @@ -25,7 +27,8 @@ "ug": "yarn upgrade-interactive" }, "dependencies": { - "@ai-sdk/openai": "2.0.80", + "@ai-sdk/openai": "2.0.88", + "@ai-sdk/react": "2.0.118", "@apidevtools/json-schema-ref-parser": "15.1.3", "@blockprotocol/graph": "0.4.0-canary.2", "@blockprotocol/type-system": "0.1.2-canary.1", @@ -37,18 +40,25 @@ "@local/hash-graph-sdk": "0.0.0-private", "@local/hash-isomorphic-utils": "0.0.0-private", "@local/status": "0.0.0-private", - "@mastra/core": "1.0.0-beta.10", + "@mastra/ai-sdk": "1.0.0-beta.10", + "@mastra/client-js": "1.0.0-beta.14", + "@mastra/core": "1.0.0-beta.14", "@mastra/evals": "1.0.0-beta.2", - "@mastra/libsql": "1.0.0-beta.7", + "@mastra/libsql": "1.0.0-beta.8", "@mastra/loggers": "1.0.0-beta.3", "@mastra/mcp": "1.0.0-beta.6", - "@mastra/memory": "1.0.0-beta.4", - "@mastra/observability": "1.0.0-beta.4", + "@mastra/memory": "1.0.0-beta.6", + "@mastra/observability": "1.0.0-beta.6", + "@mastra/react": "0.1.0-beta.14", "@sinclair/typebox": "0.34.41", + "ai": "5.0.112", "dedent": "1.7.0", "es-toolkit": "1.41.0", "json-schema": "0.4.0", "picocolors": "1.1.1", + "react": "19.1.0", + "react-dom": "19.1.0", + "react-router": "7.10.1", "vitest": "4.0.15", "zod": "4.1.12", "zod-from-json-schema": "0.5.2" @@ -64,16 +74,20 @@ "@types/mime-types": "2.1.4", "@types/node": "22.18.13", "@types/papaparse": "5.3.16", + "@types/react": "19.1.8", + "@types/react-dom": "19.1.6", "@types/sanitize-html": "2.16.0", "@vitest/coverage-istanbul": "3.2.4", "baseline-browser-mapping": "2.9.11", + "concurrently": "9.2.1", "eslint": "9.38.0", "jsdom": "24.1.3", "mastra": "1.0.0-beta.5", "npm-run-all2": "8.0.4", "sanitize-html": "2.17.0", "tsx": "4.20.6", - "typescript": "5.9.3" + "typescript": "5.9.3", + "vite": "7.0.7" }, "engines": { "node": ">=22.13.0" diff --git a/apps/hash-ai-agent/src/client/README.md b/apps/hash-ai-agent/src/client/README.md new file mode 100644 index 00000000000..b18451dff63 --- /dev/null +++ b/apps/hash-ai-agent/src/client/README.md @@ -0,0 +1,188 @@ +# HASH AI Agent - Client + +A minimal React chat frontend that connects to the Mastra backend server. + +## Architecture + +This setup runs **two separate processes**: + +``` +┌─────────────────────┐ ┌─────────────────────┐ +│ Vite Dev Server │ │ Mastra Server │ +│ (port 5173) │ ──────▶ │ (port 4111) │ +│ │ HTTP │ │ +│ React SPA │ proxy │ Agents, Workflows │ +│ - Chat UI │ │ - /chat/:agentId │ +│ - react-router │ │ - /api/* │ +└─────────────────────┘ └─────────────────────┘ +``` + +- **Mastra server** (`yarn dev:mastra`): Runs your agents, workflows, and storage +- **Vite client** (`yarn dev:client`): Serves the React SPA, proxies API requests + +## Quick Start + +```bash +# From apps/hash-ai-agent directory + +# Install dependencies (if not already done) +yarn + +# Start both servers concurrently +yarn dev + +# Or run them separately: +yarn dev:mastra # Start Mastra on port 4111 +yarn dev:client # Start Vite on port 5173 +``` + +Open http://localhost:5173 to use the chat interface. + +## Key Files + +``` +src/ +├── mastra/ # Mastra server (agents, workflows) +│ └── index.ts # Mastra config with chatRoute() +└── client/ # React client (this directory) + ├── index.html # HTML entry point + ├── vite.config.ts # Vite config with proxy settings + ├── tsconfig.json # TypeScript config for JSX + ├── README.md # This file + ├── main.tsx # React entry point + ├── app.tsx # Router setup + └── components/ + └── chat.tsx # Chat UI using useChat() +``` + +## How It Works + +### Server Side (Mastra) + +The Mastra server configuration in `src/mastra/index.ts` includes: + +```typescript +import { chatRoute } from "@mastra/ai-sdk"; + +export const mastra = new Mastra({ + agents: { myAgent, anotherAgent }, + server: { + port: 4111, + cors: { origin: ["http://localhost:5173"] }, + apiRoutes: [ + // Creates POST /chat/:agentId endpoint + chatRoute({ path: "/chat/:agentId" }), + ], + }, +}); +``` + +The `chatRoute()` helper from `@mastra/ai-sdk` creates an AI SDK v5 compatible streaming endpoint. + +### Client Side (React) + +The chat component uses `useChat()` from `@ai-sdk/react`: + +```typescript +import { useChat } from "@ai-sdk/react"; +import { DefaultChatTransport } from "ai"; + +function Chat() { + const { messages, input, setInput, handleSubmit, status } = useChat({ + transport: new DefaultChatTransport({ + api: `/chat/myAgent`, // Proxied to Mastra server + }), + }); + + // ... render messages and input form +} +``` + +### CORS & Proxy + +During development, Vite proxies `/chat/*` and `/api/*` requests to the Mastra server. This avoids CORS issues by making requests same-origin from the browser's perspective. + +For production, you have two options: +1. Configure your production server to proxy requests similarly +2. Set appropriate CORS headers on the Mastra server + +## Packages Used + +| Package | Purpose | +|---------|---------| +| `@mastra/ai-sdk` | `chatRoute()` helper for AI SDK streaming | +| `@ai-sdk/react` | `useChat()` hook for client-side chat | +| `ai` | Vercel AI SDK core (DefaultChatTransport) | +| `react-router` | Client-side routing | +| `vite` | Dev server with HMR and proxy | + +## Adding More Features + +### Custom API Routes + +Add routes in `src/mastra/index.ts`: + +```typescript +import { registerApiRoute } from "@mastra/core/server"; + +server: { + apiRoutes: [ + chatRoute({ path: "/chat/:agentId" }), + + // Custom endpoint + registerApiRoute("/api/status", { + method: "GET", + handler: async (c) => { + return c.json({ status: "ok" }); + }, + }), + ], +} +``` + +### Workflow Streaming + +For workflows, use `workflowRoute()`: + +```typescript +import { workflowRoute } from "@mastra/ai-sdk"; + +apiRoutes: [ + workflowRoute({ path: "/workflow/:workflowId" }), +] +``` + +### Using @mastra/react + +For more Mastra-specific features, wrap your app with `MastraReactProvider`: + +```typescript +import { MastraReactProvider, useMastraClient } from "@mastra/react"; + +function App() { + return ( + + + + ); +} + +function MyComponent() { + const client = useMastraClient(); + // client.listAgents(), client.getAgent(id).details(), etc. +} +``` + +## Troubleshooting + +### "Failed to fetch" or Network Errors +- Ensure Mastra server is running (`yarn dev:mastra`) +- Check that port 4111 is not in use by another process + +### Agent Not Found +- Verify the agent ID matches one registered in `src/mastra/index.ts` +- Check Mastra server logs for errors + +### CORS Errors in Production +- Configure CORS in Mastra server config: `server.cors.origin` +- Or set up a reverse proxy in your production infrastructure diff --git a/apps/hash-ai-agent/src/client/app.tsx b/apps/hash-ai-agent/src/client/app.tsx new file mode 100644 index 00000000000..27c4c115a89 --- /dev/null +++ b/apps/hash-ai-agent/src/client/app.tsx @@ -0,0 +1,53 @@ +/** + * Main App component with React Router setup. + * + * Architecture: + * - This is a client-only React SPA + * - It connects to the Mastra server (port 4111) via HTTP + * - Vite's dev server proxies /chat/* to avoid CORS issues + * - For production, configure your server to handle routing + */ +import { BrowserRouter, Link, Route, Routes } from "react-router"; + +import { Chat } from "./components/chat"; + +export const App = () => { + return ( + +
+ {/* Simple navigation header */} +
+

+ HASH AI Agent +

+ +
+ + {/* Main content area */} +
+ + } /> + +
+
+ + ); +}; diff --git a/apps/hash-ai-agent/src/client/components/chat.tsx b/apps/hash-ai-agent/src/client/components/chat.tsx new file mode 100644 index 00000000000..09282179383 --- /dev/null +++ b/apps/hash-ai-agent/src/client/components/chat.tsx @@ -0,0 +1,249 @@ +/** + * Minimal chat component using AI SDK's useChat hook. + * + * Key concepts: + * 1. useChat() from @ai-sdk/react manages message state and streaming + * 2. DefaultChatTransport connects to our Mastra server's chatRoute() + * 3. The :agentId in the URL path selects which agent to chat with + * + * The Mastra server exposes: POST /chat/:agentId + * - Request body: { messages: [{ role: 'user' | 'assistant', content: string }] } + * - Response: Server-Sent Events stream in AI SDK v5 format + */ +import { useChat } from "@ai-sdk/react"; +import type { UIMessage } from "ai"; +import { DefaultChatTransport } from "ai"; +import type { ChangeEvent, FormEvent } from "react"; +import { useState } from "react"; + +/** + * Available agents registered in src/mastra/index.ts + * These correspond to the agents object in the Mastra config + */ +const AGENTS = [ + { id: "genericAgent", label: "Generic Agent" }, + { id: "plannerAgent", label: "Planner Agent" }, + { id: "nerAgent", label: "NER Agent" }, +] as const; + +/** + * Render message parts from AI SDK v5 format. + * Messages can contain text, reasoning, tool calls, etc. + */ +const renderMessageParts = (message: UIMessage) => { + if (message.parts.length === 0) { + // Fallback for messages without parts + return null; + } + + return message.parts.map((part, index) => { + const key = `${message.id}-part-${index}`; + + if (part.type === "text") { + return {part.text}; + } + + if (part.type === "reasoning") { + return ( +
+ Reasoning + 
+            {part.text}
+
+
+ ); + } + + return null; + }); +}; + +export const Chat = () => { + // Track which agent is selected + const [agentId, setAgentId] = useState(AGENTS[0].id); + + // Track input separately (AI SDK v5 pattern) + const [input, setInput] = useState(""); + + // useChat manages the message history and streaming state + // The transport defines how to connect to the backend + const { messages, sendMessage, status, error } = useChat({ + // Connect to Mastra's chatRoute() endpoint + // Vite's proxy forwards /chat/* to localhost:4111 + transport: new DefaultChatTransport({ + api: `/chat/${agentId}`, + }), + // Reset messages when agent changes + id: agentId, + }); + + const handleAgentChange = (event: ChangeEvent) => { + setAgentId(event.target.value); + }; + + const handleInputChange = (event: ChangeEvent) => { + setInput(event.target.value); + }; + + const handleFormSubmit = (event: FormEvent) => { + event.preventDefault(); + if (input.trim() === "") { + return; + } + void sendMessage({ text: input }); + setInput(""); + }; + + return ( +
+ {/* Agent selector */} +
+ +
+ + {/* Messages display area */} +
+ {messages.length === 0 ? ( +

+ Start a conversation with{" "} + {AGENTS.find((agent) => agent.id === agentId)?.label} +

+ ) : ( + messages.map((message) => ( +
+
+ {message.role === "user" ? "You" : "Agent"} +
+
+ {renderMessageParts(message)} +
+
+ )) + )} + + {/* Show loading state while streaming */} + {status === "streaming" ? ( +
+ Agent is typing... +
+ ) : null} + + {/* Show errors if any */} + {error ? ( +
+ Error: {error.message} +
+ ) : null} +
+ + {/* Input form */} +
+ + +
+
+ ); +}; diff --git a/apps/hash-ai-agent/src/client/index.html b/apps/hash-ai-agent/src/client/index.html new file mode 100644 index 00000000000..8cb9178a7b7 --- /dev/null +++ b/apps/hash-ai-agent/src/client/index.html @@ -0,0 +1,28 @@ + + + + + + HASH AI Agent - Chat + + + +
+ + + diff --git a/apps/hash-ai-agent/src/client/main.tsx b/apps/hash-ai-agent/src/client/main.tsx new file mode 100644 index 00000000000..b821e085a82 --- /dev/null +++ b/apps/hash-ai-agent/src/client/main.tsx @@ -0,0 +1,16 @@ +/** + * Client entry point for the HASH AI Agent chat interface. + * + * This is a minimal React SPA that connects to the Mastra server backend. + * The server runs on port 4111, and Vite proxies /chat/* requests to it. + */ +import { StrictMode } from "react"; +import { createRoot } from "react-dom/client"; + +import { App } from "./app"; + +createRoot(document.getElementById("root")!).render( + + + , +); diff --git a/apps/hash-ai-agent/src/client/tsconfig.json b/apps/hash-ai-agent/src/client/tsconfig.json new file mode 100644 index 00000000000..0fd92d3fad1 --- /dev/null +++ b/apps/hash-ai-agent/src/client/tsconfig.json @@ -0,0 +1,17 @@ +{ + "compilerOptions": { + "target": "ES2022", + "lib": ["ES2022", "DOM", "DOM.Iterable"], + "module": "ESNext", + "moduleResolution": "bundler", + "jsx": "react-jsx", + "strict": true, + "noEmit": true, + "isolatedModules": true, + "skipLibCheck": true, + "esModuleInterop": true, + "allowSyntheticDefaultImports": true, + "resolveJsonModule": true + }, + "include": ["./**/*.ts", "./**/*.tsx"] +} diff --git a/apps/hash-ai-agent/src/client/vite.config.ts b/apps/hash-ai-agent/src/client/vite.config.ts new file mode 100644 index 00000000000..93ebd7cc16a --- /dev/null +++ b/apps/hash-ai-agent/src/client/vite.config.ts @@ -0,0 +1,32 @@ +import path from "node:path"; + +import { defineConfig } from "vite"; + +/** + * Vite configuration for the client-side React app. + * + * This runs separately from the Mastra server and connects via HTTP. + * The root is set to the client/ directory so Vite finds index.html there. + */ +export default defineConfig({ + root: path.resolve(__dirname), + server: { + port: 5173, + // Proxy API requests to Mastra server during development + // This avoids CORS issues by making requests same-origin + proxy: { + "/api": { + target: "http://localhost:4111", + changeOrigin: true, + }, + "/chat": { + target: "http://localhost:4111", + changeOrigin: true, + }, + }, + }, + // Enable JSX transform + esbuild: { + jsx: "automatic", + }, +}); diff --git a/apps/hash-ai-agent/src/mastra/index.ts b/apps/hash-ai-agent/src/mastra/index.ts index 6f9a9405523..0974b6b5323 100644 --- a/apps/hash-ai-agent/src/mastra/index.ts +++ b/apps/hash-ai-agent/src/mastra/index.ts @@ -2,6 +2,7 @@ import path from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; +import { chatRoute } from "@mastra/ai-sdk"; import { Mastra } from "@mastra/core/mastra"; import { LibSQLStore } from "@mastra/libsql"; import { PinoLogger } from "@mastra/loggers"; @@ -33,4 +34,33 @@ export const mastra = new Mastra({ observability: new Observability({ default: { enabled: true }, }), + /** + * Server configuration for the Mastra backend. + * + * The server runs on port 4111 (default) and exposes: + * - Built-in API routes for agents, workflows, memory at /api/* + * - Custom routes registered via apiRoutes array + * + * The chatRoute() helper from @mastra/ai-sdk creates an AI SDK v5 compatible + * streaming endpoint that works with useChat() from @ai-sdk/react. + */ + server: { + port: 4111, + // Allow requests from the Vite dev server (default port 5173) + cors: { + origin: ["http://localhost:5173", "http://127.0.0.1:5173"], + allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"], + allowHeaders: ["Content-Type", "Authorization"], + }, + apiRoutes: [ + // AI SDK streaming chat endpoint + // Usage: POST /chat/:agentId with { messages: [...] } + // The :agentId param allows routing to any registered agent + chatRoute({ + path: "/chat/:agentId", + // Include reasoning steps in the stream (useful for debugging) + sendReasoning: true, + }), + ], + }, }); diff --git a/apps/hash-ai-agent/tsconfig.json b/apps/hash-ai-agent/tsconfig.json index b10e82bc412..e16a546d99f 100644 --- a/apps/hash-ai-agent/tsconfig.json +++ b/apps/hash-ai-agent/tsconfig.json @@ -2,6 +2,7 @@ "compilerOptions": { "target": "ES2022", "module": "ES2022", + "jsx": "react-jsx", "moduleResolution": "bundler", "resolveJsonModule": true, "esModuleInterop": true, diff --git a/yarn.lock b/yarn.lock index 1d7e715e6c1..99b1f797d45 100644 --- a/yarn.lock +++ b/yarn.lock @@ -26,32 +26,6 @@ __metadata: languageName: node linkType: hard -"@ai-sdk/azure@npm:^2.0.0": - version: 2.0.87 - resolution: "@ai-sdk/azure@npm:2.0.87" - dependencies: - "@ai-sdk/openai": "npm:2.0.85" - "@ai-sdk/provider": "npm:2.0.0" - "@ai-sdk/provider-utils": "npm:3.0.19" - peerDependencies: - zod: ^3.25.76 || ^4.1.8 - checksum: 10c0/77b0c74966144c3ca715e8357bd36502bd7055edb74a4005d9537cf9175cd9b33df32164a5e3f1925b1d311ed1a4eaf5b8fad6abdb81e1b6c14ba5ea78479f34 - languageName: node - linkType: hard - -"@ai-sdk/gateway@npm:1.0.33": - version: 1.0.33 - resolution: "@ai-sdk/gateway@npm:1.0.33" - dependencies: - "@ai-sdk/provider": "npm:2.0.0" - "@ai-sdk/provider-utils": "npm:3.0.10" - "@vercel/oidc": "npm:^3.0.1" - peerDependencies: - zod: ^3.25.76 || ^4.1.8 - checksum: 10c0/81e464b127acaf09e63830ca2c961be847a73feb2e985b721404143dbc4a516d6bc738fb9532ec6d660dc41a649e828ed10113a3b3805a31493740a0640b114c - languageName: node - linkType: hard - "@ai-sdk/gateway@npm:2.0.12": version: 2.0.12 resolution: "@ai-sdk/gateway@npm:2.0.12" @@ -65,27 +39,15 @@ __metadata: languageName: node linkType: hard -"@ai-sdk/openai@npm:2.0.80": - version: 2.0.80 - resolution: "@ai-sdk/openai@npm:2.0.80" - dependencies: - "@ai-sdk/provider": "npm:2.0.0" - "@ai-sdk/provider-utils": "npm:3.0.18" - peerDependencies: - zod: ^3.25.76 || ^4.1.8 - checksum: 10c0/329c9ad0e4bb6be46766e13caca6ee2ee7b9868b4007919db8edabb53f4b1ad04995e1fce5868c20879afe4b0a5900eba0544030e72f749f8f687341aeea5a4e - languageName: node - linkType: hard - -"@ai-sdk/openai@npm:2.0.85": - version: 2.0.85 - resolution: "@ai-sdk/openai@npm:2.0.85" +"@ai-sdk/openai@npm:2.0.88": + version: 2.0.88 + resolution: "@ai-sdk/openai@npm:2.0.88" dependencies: "@ai-sdk/provider": "npm:2.0.0" "@ai-sdk/provider-utils": "npm:3.0.19" peerDependencies: zod: ^3.25.76 || ^4.1.8 - checksum: 10c0/c8e50de443d939d7a5d7444e1a2ff35357d05dd3add0fca8226b578b199f4ca53c8a9e22c376e88006466b86e39c88d7ceca790a6a866300e3964ad24756d580 + checksum: 10c0/433e90fb68c92e9b0a777b373e83032035fe62fa95b1db580fecc904cc9774c5894454fe67fb2a78e9ffa412fb19ba954e6257c216ffc4929533931bab66aa64 languageName: node linkType: hard @@ -102,6 +64,29 @@ __metadata: languageName: node linkType: hard +"@ai-sdk/provider-utils-v6@npm:@ai-sdk/provider-utils@4.0.0-beta.47": + version: 4.0.0-beta.47 + resolution: "@ai-sdk/provider-utils@npm:4.0.0-beta.47" + dependencies: + "@ai-sdk/provider": "npm:3.0.0-beta.26" + "@standard-schema/spec": "npm:^1.0.0" + eventsource-parser: "npm:^3.0.6" + peerDependencies: + "@valibot/to-json-schema": ^1.3.0 + arktype: ^2.1.22 + effect: ^3.18.4 + zod: ^3.25.76 || ^4.1.8 + peerDependenciesMeta: + "@valibot/to-json-schema": + optional: true + arktype: + optional: true + effect: + optional: true + checksum: 10c0/2db62c895867f8cf8f2f55f19974af2bf8826f14d0b4c5931fd9dfb27612d45c53626b329b9fb314ed729c77de067339875dfe3f8c3ea531cd07675a1dcbd732 + languageName: node + linkType: hard + "@ai-sdk/provider-utils@npm:2.2.8": version: 2.2.8 resolution: "@ai-sdk/provider-utils@npm:2.2.8" @@ -115,19 +100,6 @@ __metadata: languageName: node linkType: hard -"@ai-sdk/provider-utils@npm:3.0.10": - version: 3.0.10 - resolution: "@ai-sdk/provider-utils@npm:3.0.10" - dependencies: - "@ai-sdk/provider": "npm:2.0.0" - "@standard-schema/spec": "npm:^1.0.0" - eventsource-parser: "npm:^3.0.5" - peerDependencies: - zod: ^3.25.76 || ^4.1.8 - checksum: 10c0/d2c16abdb84ba4ef48c9f56190b5ffde224b9e6ae5147c5c713d2623627732d34b96aa9aef2a2ea4b0c49e1b863cc963c7d7ff964a1dc95f0f036097aaaaaa98 - languageName: node - linkType: hard - "@ai-sdk/provider-utils@npm:3.0.17": version: 3.0.17 resolution: "@ai-sdk/provider-utils@npm:3.0.17" @@ -141,19 +113,6 @@ __metadata: languageName: node linkType: hard -"@ai-sdk/provider-utils@npm:3.0.18": - version: 3.0.18 - resolution: "@ai-sdk/provider-utils@npm:3.0.18" - dependencies: - "@ai-sdk/provider": "npm:2.0.0" - "@standard-schema/spec": "npm:^1.0.0" - eventsource-parser: "npm:^3.0.6" - peerDependencies: - zod: ^3.25.76 || ^4.1.8 - checksum: 10c0/209c15b0dceef0ba95a7d3de544be0a417ad4a0bd5143496b3966a35fedf144156d93a42ff8c3d7db56781b9836bafc8c132c98978c49240e55bc1a36e18a67f - languageName: node - linkType: hard - "@ai-sdk/provider-utils@npm:3.0.19": version: 3.0.19 resolution: "@ai-sdk/provider-utils@npm:3.0.19" @@ -176,6 +135,15 @@ __metadata: languageName: node linkType: hard +"@ai-sdk/provider-v6@npm:@ai-sdk/provider@3.0.0-beta.26, @ai-sdk/provider@npm:3.0.0-beta.26": + version: 3.0.0-beta.26 + resolution: "@ai-sdk/provider@npm:3.0.0-beta.26" + dependencies: + json-schema: "npm:^0.4.0" + checksum: 10c0/f040d5797fca5241461806ac6cb17f98e6bf218a30317994126a70a41f4e2197fbf2a221088db3a7cdd5df641528f7e97b63d56573b5fd100bc657b2f3a069d6 + languageName: node + linkType: hard + "@ai-sdk/provider@npm:1.1.3": version: 1.1.3 resolution: "@ai-sdk/provider@npm:1.1.3" @@ -185,6 +153,24 @@ __metadata: languageName: node linkType: hard +"@ai-sdk/react@npm:2.0.118": + version: 2.0.118 + resolution: "@ai-sdk/react@npm:2.0.118" + dependencies: + "@ai-sdk/provider-utils": "npm:3.0.19" + ai: "npm:5.0.116" + swr: "npm:^2.2.5" + throttleit: "npm:2.1.0" + peerDependencies: + react: ^18 || ~19.0.1 || ~19.1.2 || ^19.2.1 + zod: ^3.25.76 || ^4.1.8 + peerDependenciesMeta: + zod: + optional: true + checksum: 10c0/ad433f1a1862ef16d5067b5e6b0d3e182a941e1a2920384262ac57bf84c3ed4af8d5ddafb9e30fbc5435ea72b643b9ee9dc20747b8b9d5e0f2ced69f91ba22ec + languageName: node + linkType: hard + "@ai-sdk/ui-utils-v5@npm:@ai-sdk/ui-utils@1.2.11": version: 1.2.11 resolution: "@ai-sdk/ui-utils@npm:1.2.11" @@ -577,7 +563,8 @@ __metadata: version: 0.0.0-use.local resolution: "@apps/hash-ai-agent@workspace:apps/hash-ai-agent" dependencies: - "@ai-sdk/openai": "npm:2.0.80" + "@ai-sdk/openai": "npm:2.0.88" + "@ai-sdk/react": "npm:2.0.118" "@apidevtools/json-schema-ref-parser": "npm:15.1.3" "@blockprotocol/graph": "npm:0.4.0-canary.2" "@blockprotocol/type-system": "npm:0.1.2-canary.1" @@ -591,13 +578,16 @@ __metadata: "@local/hash-isomorphic-utils": "npm:0.0.0-private" "@local/status": "npm:0.0.0-private" "@local/tsconfig": "npm:0.0.0-private" - "@mastra/core": "npm:1.0.0-beta.10" + "@mastra/ai-sdk": "npm:1.0.0-beta.10" + "@mastra/client-js": "npm:1.0.0-beta.14" + "@mastra/core": "npm:1.0.0-beta.14" "@mastra/evals": "npm:1.0.0-beta.2" - "@mastra/libsql": "npm:1.0.0-beta.7" + "@mastra/libsql": "npm:1.0.0-beta.8" "@mastra/loggers": "npm:1.0.0-beta.3" "@mastra/mcp": "npm:1.0.0-beta.6" - "@mastra/memory": "npm:1.0.0-beta.4" - "@mastra/observability": "npm:1.0.0-beta.4" + "@mastra/memory": "npm:1.0.0-beta.6" + "@mastra/observability": "npm:1.0.0-beta.6" + "@mastra/react": "npm:0.1.0-beta.14" "@sinclair/typebox": "npm:0.34.41" "@types/dedent": "npm:0.7.2" "@types/dotenv-flow": "npm:3.3.3" @@ -607,9 +597,13 @@ __metadata: "@types/mime-types": "npm:2.1.4" "@types/node": "npm:22.18.13" "@types/papaparse": "npm:5.3.16" + "@types/react": "npm:19.1.8" + "@types/react-dom": "npm:19.1.6" "@types/sanitize-html": "npm:2.16.0" "@vitest/coverage-istanbul": "npm:3.2.4" + ai: "npm:5.0.112" baseline-browser-mapping: "npm:2.9.11" + concurrently: "npm:9.2.1" dedent: "npm:1.7.0" es-toolkit: "npm:1.41.0" eslint: "npm:9.38.0" @@ -618,9 +612,13 @@ __metadata: mastra: "npm:1.0.0-beta.5" npm-run-all2: "npm:8.0.4" picocolors: "npm:1.1.1" + react: "npm:19.1.0" + react-dom: "npm:19.1.0" + react-router: "npm:7.10.1" sanitize-html: "npm:2.17.0" tsx: "npm:4.20.6" typescript: "npm:5.9.3" + vite: "npm:7.0.7" vitest: "npm:4.0.15" zod: "npm:4.1.12" zod-from-json-schema: "npm:0.5.2" @@ -10904,22 +10902,45 @@ __metadata: languageName: node linkType: hard -"@mastra/core@npm:1.0.0-beta.10": +"@mastra/ai-sdk@npm:1.0.0-beta.10": version: 1.0.0-beta.10 - resolution: "@mastra/core@npm:1.0.0-beta.10" + resolution: "@mastra/ai-sdk@npm:1.0.0-beta.10" + peerDependencies: + "@mastra/core": ">=1.0.0-0 <2.0.0-0" + zod: ^3.25.0 || ^4.0.0 + checksum: 10c0/23ca2333568c8d5b8ed36f6ec5a2ed1772b18cbf0b7b671b883566cff7173c374df4f1fee0562c97e8bad0cf5166cc4ff2967e5814c41cee26a567616055888f + languageName: node + linkType: hard + +"@mastra/client-js@npm:1.0.0-beta.14": + version: 1.0.0-beta.14 + resolution: "@mastra/client-js@npm:1.0.0-beta.14" + dependencies: + "@lukeed/uuid": "npm:^2.0.1" + "@mastra/core": "npm:1.0.0-beta.14" + "@mastra/schema-compat": "npm:1.0.0-beta.3" + json-schema: "npm:^0.4.0" + peerDependencies: + zod: ^3.25.0 || ^4.0.0 + checksum: 10c0/6cd5c86b4393e67d5f6346cdc866dcf4828b33fd4b3bbe4e948538ab76553b3a90f6d6f26a2ea469be7636bebfbb591c3d202a22cd3ab2c997f6d3b061f2b615 + languageName: node + linkType: hard + +"@mastra/core@npm:1.0.0-beta.14": + version: 1.0.0-beta.14 + resolution: "@mastra/core@npm:1.0.0-beta.14" dependencies: "@a2a-js/sdk": "npm:~0.2.4" - "@ai-sdk/azure": "npm:^2.0.0" "@ai-sdk/provider-utils-v5": "npm:@ai-sdk/provider-utils@3.0.12" + "@ai-sdk/provider-utils-v6": "npm:@ai-sdk/provider-utils@4.0.0-beta.47" "@ai-sdk/provider-v5": "npm:@ai-sdk/provider@2.0.0" + "@ai-sdk/provider-v6": "npm:@ai-sdk/provider@3.0.0-beta.26" "@ai-sdk/ui-utils-v5": "npm:@ai-sdk/ui-utils@1.2.11" "@isaacs/ttlcache": "npm:^1.4.1" "@lukeed/uuid": "npm:^2.0.1" - "@mastra/schema-compat": "npm:1.0.0-beta.2" + "@mastra/schema-compat": "npm:1.0.0-beta.3" "@modelcontextprotocol/sdk": "npm:^1.17.5" - "@openrouter/ai-sdk-provider-v5": "npm:@openrouter/ai-sdk-provider@1.2.3" "@sindresorhus/slugify": "npm:^2.2.1" - ai-v5: "npm:ai@5.0.97" dotenv: "npm:^16.6.1" hono: "npm:^4.10.5" hono-openapi: "npm:^1.1.1" @@ -10931,12 +10952,8 @@ __metadata: radash: "npm:^12.1.1" xxhash-wasm: "npm:^1.1.0" peerDependencies: - "@mastra/observability": ">=1.0.0-0 <2.0.0-0" zod: ^3.25.0 || ^4.0.0 - peerDependenciesMeta: - "@mastra/observability": - optional: true - checksum: 10c0/7570519b18474b8e5bd0516648896c229b62462b7bc480b408ee7ae67a5d696fa97241a61ddf4733e593237572624cb9a49952fc20d424dc92ac37761c526d87 + checksum: 10c0/f6cc137a4a11610e7568a2e01e457093db4e18027725a1c721e60652c6eaf2314ea1d5d0ef2ba35e62e973f035614d7dba8637f2e4ae95b5c65642564f54fed8 languageName: node linkType: hard @@ -10990,14 +11007,14 @@ __metadata: languageName: node linkType: hard -"@mastra/libsql@npm:1.0.0-beta.7": - version: 1.0.0-beta.7 - resolution: "@mastra/libsql@npm:1.0.0-beta.7" +"@mastra/libsql@npm:1.0.0-beta.8": + version: 1.0.0-beta.8 + resolution: "@mastra/libsql@npm:1.0.0-beta.8" dependencies: "@libsql/client": "npm:^0.15.15" peerDependencies: "@mastra/core": ">=1.0.0-0 <2.0.0-0" - checksum: 10c0/ff4fbd1bd80c1248e8dbc0ad600b381b67d71c29e0889a4feee7697bd2716d199a80a8de5ad75306e6800e2b7b28dd5a9689126ac4a9e2a13a4fc2126e31ef3f + checksum: 10c0/55bd8aabdc2ce44b1b985ac0cc257cdc80c5bf5b90b26b319b33c6245ecd90fbabdbf8b4cf88837227b1a5af99e141004b1957388c952b86c974b38498d095c6 languageName: node linkType: hard @@ -11031,13 +11048,11 @@ __metadata: languageName: node linkType: hard -"@mastra/memory@npm:1.0.0-beta.4": - version: 1.0.0-beta.4 - resolution: "@mastra/memory@npm:1.0.0-beta.4" +"@mastra/memory@npm:1.0.0-beta.6": + version: 1.0.0-beta.6 + resolution: "@mastra/memory@npm:1.0.0-beta.6" dependencies: - "@mastra/schema-compat": "npm:1.0.0-beta.2" - ai: "npm:^4.3.19" - ai-v5: "npm:ai@5.0.60" + "@mastra/schema-compat": "npm:1.0.0-beta.3" async-mutex: "npm:^0.5.0" js-tiktoken: "npm:^1.0.20" json-schema: "npm:^0.4.0" @@ -11046,33 +11061,48 @@ __metadata: peerDependencies: "@mastra/core": ">=1.0.0-0 <2.0.0-0" zod: ^3.25.0 || ^4.0.0 - checksum: 10c0/0cd73b240078b33b975539a0397c6fc170a5d0a1fb8ebd8e447b60673102acb5117410929947f0b482b4c2fb5ff88684cf4d29185db05115269979b97aac8c2b + checksum: 10c0/6728f2613e7d4e592a266f86fc6a8110f770c70fd3d8c9c66e401e2dc9015d3c86450f2d308a85fec48dc1ea725d6b38ffc67b5ae815ba9b9cfbcd7a9699af84 languageName: node linkType: hard -"@mastra/observability@npm:1.0.0-beta.4": - version: 1.0.0-beta.4 - resolution: "@mastra/observability@npm:1.0.0-beta.4" - dependencies: - zod: "npm:^3.25.76" +"@mastra/observability@npm:1.0.0-beta.6": + version: 1.0.0-beta.6 + resolution: "@mastra/observability@npm:1.0.0-beta.6" peerDependencies: "@mastra/core": ">=1.0.0-0 <2.0.0-0" - checksum: 10c0/2bbe490f064fb6a58df16d95c67955a1a7d1b921655cf8518c54317a7ff4a68021ac11561be355332149b38685daa5830daecde8da69193ebdb497f539cf34c0 + checksum: 10c0/67a118ff4080f0e4b05df46e85a7214c5014bf7d5b06c6495e271bad9b3dcb835a26686d6a662649d0f19436a53695b77e09348fe7bd13f09f48dabbde7b1f8d languageName: node linkType: hard -"@mastra/schema-compat@npm:1.0.0-beta.2": - version: 1.0.0-beta.2 - resolution: "@mastra/schema-compat@npm:1.0.0-beta.2" +"@mastra/react@npm:0.1.0-beta.14": + version: 0.1.0-beta.14 + resolution: "@mastra/react@npm:0.1.0-beta.14" + dependencies: + "@lukeed/uuid": "npm:^2.0.1" + "@mastra/client-js": "npm:1.0.0-beta.14" + "@radix-ui/react-tooltip": "npm:^1.2.7" + hast-util-to-jsx-runtime: "npm:^2.3.6" + lucide-react: "npm:^0.522.0" + shiki: "npm:^1.29.2" + tailwind-merge: "npm:^3.3.1" + peerDependencies: + react: ">=19.0.0" + react-dom: ">=19.0.0" + checksum: 10c0/30110373820b8cd486f8566b3032c6f108a902e96630cfabed4008800a0573c4641ddfdba3530be6a146a5437f845a0a688bd4191fa3dc64a86a09e3322c2309 + languageName: node + linkType: hard + +"@mastra/schema-compat@npm:1.0.0-beta.3": + version: 1.0.0-beta.3 + resolution: "@mastra/schema-compat@npm:1.0.0-beta.3" dependencies: - json-schema: "npm:^0.4.0" json-schema-to-zod: "npm:^2.7.0" zod-from-json-schema: "npm:^0.5.0" zod-from-json-schema-v3: "npm:zod-from-json-schema@^0.0.5" zod-to-json-schema: "npm:^3.24.6" peerDependencies: zod: ^3.25.0 || ^4.0.0 - checksum: 10c0/d0a73c7f3ec47625f71f5fdb196a16fe9e2c200cd718aefe02d705a434da1d16ae73c97fa6bd8c8d7d637a1e5654a4e24c2f03e7d7054844e543756cbfd7f4b2 + checksum: 10c0/d04921c37d400e03cd1bb6d64b2a1442b0f9724a8f1160b9f14075e11910a81ed547d44db9aab350757b302b2350cee987f3eab99c31d92cac756e6fff940580 languageName: node linkType: hard @@ -11894,27 +11924,6 @@ __metadata: languageName: node linkType: hard -"@openrouter/ai-sdk-provider-v5@npm:@openrouter/ai-sdk-provider@1.2.3": - version: 1.2.3 - resolution: "@openrouter/ai-sdk-provider@npm:1.2.3" - dependencies: - "@openrouter/sdk": "npm:^0.1.8" - peerDependencies: - ai: ^5.0.0 - zod: ^3.24.1 || ^v4 - checksum: 10c0/a4f5184b1a135ff0b6b3b382370add617d095f3dea56524dec2d174a506c4ebab318d92ae3477871206c7181cb7b9b729d0414113cdf7e797214621026c0a492 - languageName: node - linkType: hard - -"@openrouter/sdk@npm:^0.1.8": - version: 0.1.27 - resolution: "@openrouter/sdk@npm:0.1.27" - dependencies: - zod: "npm:^3.25.0 || ^4.0.0" - checksum: 10c0/c63972851b4544a6585babacb2909b8af529444c6319e0a98b8e219f75295a25d433ba1978f24c0252fbb41ac2471bf209c2728649bf0c42b7a722c3868e267e - languageName: node - linkType: hard - "@opentelemetry/api-logs@npm:0.207.0": version: 0.207.0 resolution: "@opentelemetry/api-logs@npm:0.207.0" @@ -13810,6 +13819,13 @@ __metadata: languageName: node linkType: hard +"@radix-ui/primitive@npm:1.1.3": + version: 1.1.3 + resolution: "@radix-ui/primitive@npm:1.1.3" + checksum: 10c0/88860165ee7066fa2c179f32ffcd3ee6d527d9dcdc0e8be85e9cb0e2c84834be8e3c1a976c74ba44b193f709544e12f54455d892b28e32f0708d89deda6b9f1d + languageName: node + linkType: hard + "@radix-ui/react-alert-dialog@npm:^1.0.0": version: 1.1.2 resolution: "@radix-ui/react-alert-dialog@npm:1.1.2" @@ -13873,6 +13889,25 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-arrow@npm:1.1.7": + version: 1.1.7 + resolution: "@radix-ui/react-arrow@npm:1.1.7" + dependencies: + "@radix-ui/react-primitive": "npm:2.1.3" + peerDependencies: + "@types/react": "*" + "@types/react-dom": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + "@types/react-dom": + optional: true + checksum: 10c0/c3b46766238b3ee2a394d8806a5141432361bf1425110c9f0dcf480bda4ebd304453a53f294b5399c6ee3ccfcae6fd544921fd01ddc379cf5942acdd7168664b + languageName: node + linkType: hard + "@radix-ui/react-collection@npm:1.0.3": version: 1.0.3 resolution: "@radix-ui/react-collection@npm:1.0.3" @@ -13946,6 +13981,19 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-compose-refs@npm:1.1.2": + version: 1.1.2 + resolution: "@radix-ui/react-compose-refs@npm:1.1.2" + peerDependencies: + "@types/react": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + checksum: 10c0/d36a9c589eb75d634b9b139c80f916aadaf8a68a7c1c4b8c6c6b88755af1a92f2e343457042089f04cc3f23073619d08bb65419ced1402e9d4e299576d970771 + languageName: node + linkType: hard + "@radix-ui/react-context-menu@npm:^2.1.1": version: 2.2.2 resolution: "@radix-ui/react-context-menu@npm:2.2.2" @@ -14011,6 +14059,19 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-context@npm:1.1.2": + version: 1.1.2 + resolution: "@radix-ui/react-context@npm:1.1.2" + peerDependencies: + "@types/react": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + checksum: 10c0/cece731f8cc25d494c6589cc681e5c01a93867d895c75889973afa1a255f163c286e390baa7bc028858eaabe9f6b57270d0ca6377356f652c5557c1c7a41ccce + languageName: node + linkType: hard + "@radix-ui/react-dialog@npm:1.1.2, @radix-ui/react-dialog@npm:^1.0.2": version: 1.1.2 resolution: "@radix-ui/react-dialog@npm:1.1.2" @@ -14118,6 +14179,29 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-dismissable-layer@npm:1.1.11": + version: 1.1.11 + resolution: "@radix-ui/react-dismissable-layer@npm:1.1.11" + dependencies: + "@radix-ui/primitive": "npm:1.1.3" + "@radix-ui/react-compose-refs": "npm:1.1.2" + "@radix-ui/react-primitive": "npm:2.1.3" + "@radix-ui/react-use-callback-ref": "npm:1.1.1" + "@radix-ui/react-use-escape-keydown": "npm:1.1.1" + peerDependencies: + "@types/react": "*" + "@types/react-dom": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + "@types/react-dom": + optional: true + checksum: 10c0/c825572a64073c4d3853702029979f6658770ffd6a98eabc4984e1dee1b226b4078a2a4dc7003f96475b438985e9b21a58e75f51db74dd06848dcae1f2d395dc + languageName: node + linkType: hard + "@radix-ui/react-dropdown-menu@npm:^2.0.1": version: 2.1.2 resolution: "@radix-ui/react-dropdown-menu@npm:2.1.2" @@ -14245,6 +14329,21 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-id@npm:1.1.1": + version: 1.1.1 + resolution: "@radix-ui/react-id@npm:1.1.1" + dependencies: + "@radix-ui/react-use-layout-effect": "npm:1.1.1" + peerDependencies: + "@types/react": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + checksum: 10c0/7d12e76818763d592c331277ef62b197e2e64945307e650bd058f0090e5ae48bbd07691b23b7e9e977901ef4eadcb3e2d5eaeb17a13859083384be83fc1292c7 + languageName: node + linkType: hard + "@radix-ui/react-menu@npm:2.1.2": version: 2.1.2 resolution: "@radix-ui/react-menu@npm:2.1.2" @@ -14371,6 +14470,34 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-popper@npm:1.2.8": + version: 1.2.8 + resolution: "@radix-ui/react-popper@npm:1.2.8" + dependencies: + "@floating-ui/react-dom": "npm:^2.0.0" + "@radix-ui/react-arrow": "npm:1.1.7" + "@radix-ui/react-compose-refs": "npm:1.1.2" + "@radix-ui/react-context": "npm:1.1.2" + "@radix-ui/react-primitive": "npm:2.1.3" + "@radix-ui/react-use-callback-ref": "npm:1.1.1" + "@radix-ui/react-use-layout-effect": "npm:1.1.1" + "@radix-ui/react-use-rect": "npm:1.1.1" + "@radix-ui/react-use-size": "npm:1.1.1" + "@radix-ui/rect": "npm:1.1.1" + peerDependencies: + "@types/react": "*" + "@types/react-dom": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + "@types/react-dom": + optional: true + checksum: 10c0/48e3f13eac3b8c13aca8ded37d74db17e1bb294da8d69f142ab6b8719a06c3f90051668bed64520bf9f3abdd77b382ce7ce209d056bb56137cecc949b69b421c + languageName: node + linkType: hard + "@radix-ui/react-portal@npm:1.0.3": version: 1.0.3 resolution: "@radix-ui/react-portal@npm:1.0.3" @@ -14411,6 +14538,26 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-portal@npm:1.1.9": + version: 1.1.9 + resolution: "@radix-ui/react-portal@npm:1.1.9" + dependencies: + "@radix-ui/react-primitive": "npm:2.1.3" + "@radix-ui/react-use-layout-effect": "npm:1.1.1" + peerDependencies: + "@types/react": "*" + "@types/react-dom": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + "@types/react-dom": + optional: true + checksum: 10c0/45b432497c722720c72c493a29ef6085bc84b50eafe79d48b45c553121b63e94f9cdb77a3a74b9c49126f8feb3feee009fe400d48b7759d3552396356b192cd7 + languageName: node + linkType: hard + "@radix-ui/react-presence@npm:1.1.1": version: 1.1.1 resolution: "@radix-ui/react-presence@npm:1.1.1" @@ -14431,6 +14578,26 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-presence@npm:1.1.5": + version: 1.1.5 + resolution: "@radix-ui/react-presence@npm:1.1.5" + dependencies: + "@radix-ui/react-compose-refs": "npm:1.1.2" + "@radix-ui/react-use-layout-effect": "npm:1.1.1" + peerDependencies: + "@types/react": "*" + "@types/react-dom": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + "@types/react-dom": + optional: true + checksum: 10c0/d0e61d314250eeaef5369983cb790701d667f51734bafd98cf759072755562018052c594e6cdc5389789f4543cb0a4d98f03ff4e8f37338d6b5bf51a1700c1d1 + languageName: node + linkType: hard + "@radix-ui/react-primitive@npm:1.0.3": version: 1.0.3 resolution: "@radix-ui/react-primitive@npm:1.0.3" @@ -14470,6 +14637,25 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-primitive@npm:2.1.3": + version: 2.1.3 + resolution: "@radix-ui/react-primitive@npm:2.1.3" + dependencies: + "@radix-ui/react-slot": "npm:1.2.3" + peerDependencies: + "@types/react": "*" + "@types/react-dom": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + "@types/react-dom": + optional: true + checksum: 10c0/fdff9b84913bb4172ef6d3af7442fca5f9bba5f2709cba08950071f819d7057aec3a4a2d9ef44cf9cbfb8014d02573c6884a04cff175895823aaef809ebdb034 + languageName: node + linkType: hard + "@radix-ui/react-roving-focus@npm:1.1.0": version: 1.1.0 resolution: "@radix-ui/react-roving-focus@npm:1.1.0" @@ -14597,6 +14783,21 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-slot@npm:1.2.3": + version: 1.2.3 + resolution: "@radix-ui/react-slot@npm:1.2.3" + dependencies: + "@radix-ui/react-compose-refs": "npm:1.1.2" + peerDependencies: + "@types/react": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + checksum: 10c0/5913aa0d760f505905779515e4b1f0f71a422350f077cc8d26d1aafe53c97f177fec0e6d7fbbb50d8b5e498aa9df9f707ca75ae3801540c283b26b0136138eef + languageName: node + linkType: hard + "@radix-ui/react-toast@npm:^1.1.1": version: 1.2.2 resolution: "@radix-ui/react-toast@npm:1.2.2" @@ -14627,6 +14828,36 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-tooltip@npm:^1.2.7": + version: 1.2.8 + resolution: "@radix-ui/react-tooltip@npm:1.2.8" + dependencies: + "@radix-ui/primitive": "npm:1.1.3" + "@radix-ui/react-compose-refs": "npm:1.1.2" + "@radix-ui/react-context": "npm:1.1.2" + "@radix-ui/react-dismissable-layer": "npm:1.1.11" + "@radix-ui/react-id": "npm:1.1.1" + "@radix-ui/react-popper": "npm:1.2.8" + "@radix-ui/react-portal": "npm:1.1.9" + "@radix-ui/react-presence": "npm:1.1.5" + "@radix-ui/react-primitive": "npm:2.1.3" + "@radix-ui/react-slot": "npm:1.2.3" + "@radix-ui/react-use-controllable-state": "npm:1.2.2" + "@radix-ui/react-visually-hidden": "npm:1.2.3" + peerDependencies: + "@types/react": "*" + "@types/react-dom": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + "@types/react-dom": + optional: true + checksum: 10c0/de0cbae9c571a00671f160928d819e59502f59be8749f536ab4b180181d9d70aee3925a5b2555f8f32d0bea622bc35f65b70ca7ff0449e4844f891302310cc48 + languageName: node + linkType: hard + "@radix-ui/react-use-callback-ref@npm:1.0.1": version: 1.0.1 resolution: "@radix-ui/react-use-callback-ref@npm:1.0.1" @@ -14655,6 +14886,19 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-use-callback-ref@npm:1.1.1": + version: 1.1.1 + resolution: "@radix-ui/react-use-callback-ref@npm:1.1.1" + peerDependencies: + "@types/react": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + checksum: 10c0/5f6aff8592dea6a7e46589808912aba3fb3b626cf6edd2b14f01638b61dbbe49eeb9f67cd5601f4c15b2fb547b9a7e825f7c4961acd4dd70176c969ae405f8d8 + languageName: node + linkType: hard + "@radix-ui/react-use-controllable-state@npm:1.0.1": version: 1.0.1 resolution: "@radix-ui/react-use-controllable-state@npm:1.0.1" @@ -14686,6 +14930,37 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-use-controllable-state@npm:1.2.2": + version: 1.2.2 + resolution: "@radix-ui/react-use-controllable-state@npm:1.2.2" + dependencies: + "@radix-ui/react-use-effect-event": "npm:0.0.2" + "@radix-ui/react-use-layout-effect": "npm:1.1.1" + peerDependencies: + "@types/react": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + checksum: 10c0/f55c4b06e895293aed4b44c9ef26fb24432539f5346fcd6519c7745800535b571058685314e83486a45bf61dc83887e24826490d3068acc317fb0a9010516e63 + languageName: node + linkType: hard + +"@radix-ui/react-use-effect-event@npm:0.0.2": + version: 0.0.2 + resolution: "@radix-ui/react-use-effect-event@npm:0.0.2" + dependencies: + "@radix-ui/react-use-layout-effect": "npm:1.1.1" + peerDependencies: + "@types/react": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + checksum: 10c0/e84ff72a3e76c5ae9c94941028bb4b6472f17d4104481b9eab773deab3da640ecea035e54da9d6f4df8d84c18ef6913baf92b7511bee06930dc58bd0c0add417 + languageName: node + linkType: hard + "@radix-ui/react-use-escape-keydown@npm:1.0.3": version: 1.0.3 resolution: "@radix-ui/react-use-escape-keydown@npm:1.0.3" @@ -14717,6 +14992,21 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-use-escape-keydown@npm:1.1.1": + version: 1.1.1 + resolution: "@radix-ui/react-use-escape-keydown@npm:1.1.1" + dependencies: + "@radix-ui/react-use-callback-ref": "npm:1.1.1" + peerDependencies: + "@types/react": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + checksum: 10c0/bff53be99e940fef1d3c4df7d560e1d9133182e5a98336255d3063327d1d3dd4ec54a95dc5afe15cca4fb6c184f0a956c70de2815578c318cf995a7f9beabaa1 + languageName: node + linkType: hard + "@radix-ui/react-use-layout-effect@npm:1.0.1": version: 1.0.1 resolution: "@radix-ui/react-use-layout-effect@npm:1.0.1" @@ -14745,6 +15035,19 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-use-layout-effect@npm:1.1.1": + version: 1.1.1 + resolution: "@radix-ui/react-use-layout-effect@npm:1.1.1" + peerDependencies: + "@types/react": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + checksum: 10c0/9f98fdaba008dfc58050de60a77670b885792df473cf82c1cef8daee919a5dd5a77d270209f5f0b0abfaac78cb1627396e3ff56c81b735be550409426fe8b040 + languageName: node + linkType: hard + "@radix-ui/react-use-previous@npm:1.0.1": version: 1.0.1 resolution: "@radix-ui/react-use-previous@npm:1.0.1" @@ -14804,6 +15107,21 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-use-rect@npm:1.1.1": + version: 1.1.1 + resolution: "@radix-ui/react-use-rect@npm:1.1.1" + dependencies: + "@radix-ui/rect": "npm:1.1.1" + peerDependencies: + "@types/react": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + checksum: 10c0/271711404c05c589c8dbdaa748749e7daf44bcc6bffc9ecd910821c3ebca0ee245616cf5b39653ce690f53f875c3836fd3f36f51ab1c628273b6db599eee4864 + languageName: node + linkType: hard + "@radix-ui/react-use-size@npm:1.0.1": version: 1.0.1 resolution: "@radix-ui/react-use-size@npm:1.0.1" @@ -14835,6 +15153,21 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-use-size@npm:1.1.1": + version: 1.1.1 + resolution: "@radix-ui/react-use-size@npm:1.1.1" + dependencies: + "@radix-ui/react-use-layout-effect": "npm:1.1.1" + peerDependencies: + "@types/react": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + checksum: 10c0/851d09a816f44282e0e9e2147b1b571410174cc048703a50c4fa54d672de994fd1dfff1da9d480ecfd12c77ae8f48d74f01adaf668f074156b8cd0043c6c21d8 + languageName: node + linkType: hard + "@radix-ui/react-visually-hidden@npm:1.0.3": version: 1.0.3 resolution: "@radix-ui/react-visually-hidden@npm:1.0.3" @@ -14874,6 +15207,25 @@ __metadata: languageName: node linkType: hard +"@radix-ui/react-visually-hidden@npm:1.2.3": + version: 1.2.3 + resolution: "@radix-ui/react-visually-hidden@npm:1.2.3" + dependencies: + "@radix-ui/react-primitive": "npm:2.1.3" + peerDependencies: + "@types/react": "*" + "@types/react-dom": "*" + react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc + peerDependenciesMeta: + "@types/react": + optional: true + "@types/react-dom": + optional: true + checksum: 10c0/cf86a37f1cbee50a964056f3dc4f6bb1ee79c76daa321f913aa20ff3e1ccdfafbf2b114d7bb616aeefc7c4b895e6ca898523fdb67710d89bd5d8edb739a0d9b6 + languageName: node + linkType: hard + "@radix-ui/rect@npm:1.0.1": version: 1.0.1 resolution: "@radix-ui/rect@npm:1.0.1" @@ -14890,6 +15242,13 @@ __metadata: languageName: node linkType: hard +"@radix-ui/rect@npm:1.1.1": + version: 1.1.1 + resolution: "@radix-ui/rect@npm:1.1.1" + checksum: 10c0/0dac4f0f15691199abe6a0e067821ddd9d0349c0c05f39834e4eafc8403caf724106884035ae91bbc826e10367e6a5672e7bec4d4243860fa7649de246b1f60b + languageName: node + linkType: hard + "@react-sigma/core@npm:4.0.3": version: 4.0.3 resolution: "@react-sigma/core@npm:4.0.3" @@ -15293,6 +15652,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-android-arm-eabi@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-android-arm-eabi@npm:4.54.0" + conditions: os=android & cpu=arm + languageName: node + linkType: hard + "@rollup/rollup-android-arm64@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-android-arm64@npm:4.50.2" @@ -15307,6 +15673,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-android-arm64@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-android-arm64@npm:4.54.0" + conditions: os=android & cpu=arm64 + languageName: node + linkType: hard + "@rollup/rollup-darwin-arm64@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-darwin-arm64@npm:4.50.2" @@ -15321,6 +15694,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-darwin-arm64@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-darwin-arm64@npm:4.54.0" + conditions: os=darwin & cpu=arm64 + languageName: node + linkType: hard + "@rollup/rollup-darwin-x64@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-darwin-x64@npm:4.50.2" @@ -15335,6 +15715,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-darwin-x64@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-darwin-x64@npm:4.54.0" + conditions: os=darwin & cpu=x64 + languageName: node + linkType: hard + "@rollup/rollup-freebsd-arm64@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-freebsd-arm64@npm:4.50.2" @@ -15349,6 +15736,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-freebsd-arm64@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-freebsd-arm64@npm:4.54.0" + conditions: os=freebsd & cpu=arm64 + languageName: node + linkType: hard + "@rollup/rollup-freebsd-x64@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-freebsd-x64@npm:4.50.2" @@ -15363,6 +15757,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-freebsd-x64@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-freebsd-x64@npm:4.54.0" + conditions: os=freebsd & cpu=x64 + languageName: node + linkType: hard + "@rollup/rollup-linux-arm-gnueabihf@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-linux-arm-gnueabihf@npm:4.50.2" @@ -15377,6 +15778,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-linux-arm-gnueabihf@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-linux-arm-gnueabihf@npm:4.54.0" + conditions: os=linux & cpu=arm & libc=glibc + languageName: node + linkType: hard + "@rollup/rollup-linux-arm-musleabihf@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-linux-arm-musleabihf@npm:4.50.2" @@ -15391,6 +15799,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-linux-arm-musleabihf@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-linux-arm-musleabihf@npm:4.54.0" + conditions: os=linux & cpu=arm & libc=musl + languageName: node + linkType: hard + "@rollup/rollup-linux-arm64-gnu@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-linux-arm64-gnu@npm:4.50.2" @@ -15405,6 +15820,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-linux-arm64-gnu@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-linux-arm64-gnu@npm:4.54.0" + conditions: os=linux & cpu=arm64 & libc=glibc + languageName: node + linkType: hard + "@rollup/rollup-linux-arm64-musl@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-linux-arm64-musl@npm:4.50.2" @@ -15419,6 +15841,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-linux-arm64-musl@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-linux-arm64-musl@npm:4.54.0" + conditions: os=linux & cpu=arm64 & libc=musl + languageName: node + linkType: hard + "@rollup/rollup-linux-loong64-gnu@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-linux-loong64-gnu@npm:4.50.2" @@ -15433,6 +15862,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-linux-loong64-gnu@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-linux-loong64-gnu@npm:4.54.0" + conditions: os=linux & cpu=loong64 & libc=glibc + languageName: node + linkType: hard + "@rollup/rollup-linux-ppc64-gnu@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-linux-ppc64-gnu@npm:4.50.2" @@ -15447,6 +15883,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-linux-ppc64-gnu@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-linux-ppc64-gnu@npm:4.54.0" + conditions: os=linux & cpu=ppc64 & libc=glibc + languageName: node + linkType: hard + "@rollup/rollup-linux-riscv64-gnu@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-linux-riscv64-gnu@npm:4.50.2" @@ -15461,6 +15904,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-linux-riscv64-gnu@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-linux-riscv64-gnu@npm:4.54.0" + conditions: os=linux & cpu=riscv64 & libc=glibc + languageName: node + linkType: hard + "@rollup/rollup-linux-riscv64-musl@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-linux-riscv64-musl@npm:4.50.2" @@ -15475,6 +15925,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-linux-riscv64-musl@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-linux-riscv64-musl@npm:4.54.0" + conditions: os=linux & cpu=riscv64 & libc=musl + languageName: node + linkType: hard + "@rollup/rollup-linux-s390x-gnu@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-linux-s390x-gnu@npm:4.50.2" @@ -15489,6 +15946,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-linux-s390x-gnu@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-linux-s390x-gnu@npm:4.54.0" + conditions: os=linux & cpu=s390x & libc=glibc + languageName: node + linkType: hard + "@rollup/rollup-linux-x64-gnu@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-linux-x64-gnu@npm:4.50.2" @@ -15503,6 +15967,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-linux-x64-gnu@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-linux-x64-gnu@npm:4.54.0" + conditions: os=linux & cpu=x64 & libc=glibc + languageName: node + linkType: hard + "@rollup/rollup-linux-x64-musl@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-linux-x64-musl@npm:4.50.2" @@ -15517,6 +15988,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-linux-x64-musl@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-linux-x64-musl@npm:4.54.0" + conditions: os=linux & cpu=x64 & libc=musl + languageName: node + linkType: hard + "@rollup/rollup-openharmony-arm64@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-openharmony-arm64@npm:4.50.2" @@ -15531,6 +16009,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-openharmony-arm64@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-openharmony-arm64@npm:4.54.0" + conditions: os=openharmony & cpu=arm64 + languageName: node + linkType: hard + "@rollup/rollup-win32-arm64-msvc@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-win32-arm64-msvc@npm:4.50.2" @@ -15545,6 +16030,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-win32-arm64-msvc@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-win32-arm64-msvc@npm:4.54.0" + conditions: os=win32 & cpu=arm64 + languageName: node + linkType: hard + "@rollup/rollup-win32-ia32-msvc@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-win32-ia32-msvc@npm:4.50.2" @@ -15559,6 +16051,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-win32-ia32-msvc@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-win32-ia32-msvc@npm:4.54.0" + conditions: os=win32 & cpu=ia32 + languageName: node + linkType: hard + "@rollup/rollup-win32-x64-gnu@npm:4.53.3": version: 4.53.3 resolution: "@rollup/rollup-win32-x64-gnu@npm:4.53.3" @@ -15566,6 +16065,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-win32-x64-gnu@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-win32-x64-gnu@npm:4.54.0" + conditions: os=win32 & cpu=x64 + languageName: node + linkType: hard + "@rollup/rollup-win32-x64-msvc@npm:4.50.2": version: 4.50.2 resolution: "@rollup/rollup-win32-x64-msvc@npm:4.50.2" @@ -15580,6 +16086,13 @@ __metadata: languageName: node linkType: hard +"@rollup/rollup-win32-x64-msvc@npm:4.54.0": + version: 4.54.0 + resolution: "@rollup/rollup-win32-x64-msvc@npm:4.54.0" + conditions: os=win32 & cpu=x64 + languageName: node + linkType: hard + "@rtsao/scc@npm:^1.1.0": version: 1.1.0 resolution: "@rtsao/scc@npm:1.1.0" @@ -16608,6 +17121,76 @@ __metadata: languageName: node linkType: hard +"@shikijs/core@npm:1.29.2": + version: 1.29.2 + resolution: "@shikijs/core@npm:1.29.2" + dependencies: + "@shikijs/engine-javascript": "npm:1.29.2" + "@shikijs/engine-oniguruma": "npm:1.29.2" + "@shikijs/types": "npm:1.29.2" + "@shikijs/vscode-textmate": "npm:^10.0.1" + "@types/hast": "npm:^3.0.4" + hast-util-to-html: "npm:^9.0.4" + checksum: 10c0/b1bb0567babcee64608224d652ceb4076d387b409fb8ee767f7684c68f03cfaab0e17f42d0a3372fc7be1fe165af9a3a349efc188f6e7c720d4df1108c1ab78c + languageName: node + linkType: hard + +"@shikijs/engine-javascript@npm:1.29.2": + version: 1.29.2 + resolution: "@shikijs/engine-javascript@npm:1.29.2" + dependencies: + "@shikijs/types": "npm:1.29.2" + "@shikijs/vscode-textmate": "npm:^10.0.1" + oniguruma-to-es: "npm:^2.2.0" + checksum: 10c0/b61f9e9079493c19419ff64af6454c4360a32785d47f49b41e87752e66ddbf7466dd9cce67f4d5d4a8447e31d96b4f0a39330e9f26e8bd2bc2f076644e78dff7 + languageName: node + linkType: hard + +"@shikijs/engine-oniguruma@npm:1.29.2": + version: 1.29.2 + resolution: "@shikijs/engine-oniguruma@npm:1.29.2" + dependencies: + "@shikijs/types": "npm:1.29.2" + "@shikijs/vscode-textmate": "npm:^10.0.1" + checksum: 10c0/87d77e05af7fe862df40899a7034cbbd48d3635e27706873025e5035be578584d012f850208e97ca484d5e876bf802d4e23d0394d25026adb678eeb1d1f340ff + languageName: node + linkType: hard + +"@shikijs/langs@npm:1.29.2": + version: 1.29.2 + resolution: "@shikijs/langs@npm:1.29.2" + dependencies: + "@shikijs/types": "npm:1.29.2" + checksum: 10c0/137af52ec19ab10bb167ec67e2dc6888d77dedddb3be37708569cb8e8d54c057d09df335261276012d11ac38366ba57b9eae121cc0b7045859638c25648b0563 + languageName: node + linkType: hard + +"@shikijs/themes@npm:1.29.2": + version: 1.29.2 + resolution: "@shikijs/themes@npm:1.29.2" + dependencies: + "@shikijs/types": "npm:1.29.2" + checksum: 10c0/1f7d3fc8615890d83b50c73c13e5182438dee579dd9a121d605bbdcc2dc877cafc9f7e23a3e1342345cd0b9161e3af6425b0fbfac949843f22b2a60527a8fb69 + languageName: node + linkType: hard + +"@shikijs/types@npm:1.29.2": + version: 1.29.2 + resolution: "@shikijs/types@npm:1.29.2" + dependencies: + "@shikijs/vscode-textmate": "npm:^10.0.1" + "@types/hast": "npm:^3.0.4" + checksum: 10c0/37b4ac315effc03e7185aca1da0c2631ac55bdf613897476bd1d879105c41f86ccce6ebd0b78779513d88cc2ee371039f7efd95d604f77f21f180791978822b3 + languageName: node + linkType: hard + +"@shikijs/vscode-textmate@npm:^10.0.1": + version: 10.0.2 + resolution: "@shikijs/vscode-textmate@npm:10.0.2" + checksum: 10c0/36b682d691088ec244de292dc8f91b808f95c89466af421cf84cbab92230f03c8348649c14b3251991b10ce632b0c715e416e992dd5f28ff3221dc2693fd9462 + languageName: node + linkType: hard + "@sideway/address@npm:^4.1.5": version: 4.1.5 resolution: "@sideway/address@npm:4.1.5" @@ -19789,7 +20372,7 @@ __metadata: languageName: node linkType: hard -"@types/hast@npm:^3.0.0": +"@types/hast@npm:^3.0.0, @types/hast@npm:^3.0.4": version: 3.0.4 resolution: "@types/hast@npm:3.0.4" dependencies: @@ -20212,6 +20795,15 @@ __metadata: languageName: node linkType: hard +"@types/react-dom@npm:19.1.6": + version: 19.1.6 + resolution: "@types/react-dom@npm:19.1.6" + peerDependencies: + "@types/react": ^19.0.0 + checksum: 10c0/7ba74eee2919e3f225e898b65fdaa16e54952aaf9e3472a080ddc82ca54585e46e60b3c52018d21d4b7053f09d27b8293e9f468b85f9932ff452cd290cc131e8 + languageName: node + linkType: hard + "@types/react-dom@npm:19.2.3": version: 19.2.3 resolution: "@types/react-dom@npm:19.2.3" @@ -21070,7 +21662,7 @@ __metadata: languageName: node linkType: hard -"@vercel/oidc@npm:3.0.5, @vercel/oidc@npm:^3.0.1": +"@vercel/oidc@npm:3.0.5": version: 3.0.5 resolution: "@vercel/oidc@npm:3.0.5" checksum: 10c0/a63f0ab226f9070f974334014bd2676611a2d13473c10b867e3d9db8a2cc83637ae7922db26b184dd97b5945e144fc211c8f899642d205517e5b4e0e34f05b0e @@ -22853,21 +23445,7 @@ __metadata: languageName: node linkType: hard -"ai-v5@npm:ai@5.0.60": - version: 5.0.60 - resolution: "ai@npm:5.0.60" - dependencies: - "@ai-sdk/gateway": "npm:1.0.33" - "@ai-sdk/provider": "npm:2.0.0" - "@ai-sdk/provider-utils": "npm:3.0.10" - "@opentelemetry/api": "npm:1.9.0" - peerDependencies: - zod: ^3.25.76 || ^4.1.8 - checksum: 10c0/290a9da9891e1e61a294e327a78f1f6a5ed58c92b1c14e89fd0102ae9369d803e58c299195fa8abc437380b26241b5c066e73f9a7d43cca13fe5f956629cae82 - languageName: node - linkType: hard - -"ai-v5@npm:ai@5.0.97, ai@npm:5.0.97": +"ai@npm:5.0.97": version: 5.0.97 resolution: "ai@npm:5.0.97" dependencies: @@ -26005,6 +26583,13 @@ __metadata: languageName: node linkType: hard +"cookie@npm:^1.0.1": + version: 1.1.1 + resolution: "cookie@npm:1.1.1" + checksum: 10c0/79c4ddc0fcad9c4f045f826f42edf54bcc921a29586a4558b0898277fa89fb47be95bc384c2253f493af7b29500c830da28341274527328f18eba9f58afa112c + languageName: node + linkType: hard + "cookie@npm:~1.0.1": version: 1.0.2 resolution: "cookie@npm:1.0.2" @@ -27683,6 +28268,13 @@ __metadata: languageName: node linkType: hard +"emoji-regex-xs@npm:^1.0.0": + version: 1.0.0 + resolution: "emoji-regex-xs@npm:1.0.0" + checksum: 10c0/1082de006991eb05a3324ef0efe1950c7cdf66efc01d4578de82b0d0d62add4e55e97695a8a7eeda826c305081562dc79b477ddf18d886da77f3ba08c4b940a0 + languageName: node + linkType: hard + "emoji-regex@npm:^10.3.0": version: 10.6.0 resolution: "emoji-regex@npm:10.6.0" @@ -29954,7 +30546,7 @@ __metadata: languageName: node linkType: hard -"fdir@npm:^6.2.0, fdir@npm:^6.5.0": +"fdir@npm:^6.2.0, fdir@npm:^6.4.6, fdir@npm:^6.5.0": version: 6.5.0 resolution: "fdir@npm:6.5.0" peerDependencies: @@ -31831,6 +32423,25 @@ __metadata: languageName: node linkType: hard +"hast-util-to-html@npm:^9.0.4": + version: 9.0.5 + resolution: "hast-util-to-html@npm:9.0.5" + dependencies: + "@types/hast": "npm:^3.0.0" + "@types/unist": "npm:^3.0.0" + ccount: "npm:^2.0.0" + comma-separated-tokens: "npm:^2.0.0" + hast-util-whitespace: "npm:^3.0.0" + html-void-elements: "npm:^3.0.0" + mdast-util-to-hast: "npm:^13.0.0" + property-information: "npm:^7.0.0" + space-separated-tokens: "npm:^2.0.0" + stringify-entities: "npm:^4.0.0" + zwitch: "npm:^2.0.4" + checksum: 10c0/b7a08c30bab4371fc9b4a620965c40b270e5ae7a8e94cf885f43b21705179e28c8e43b39c72885d1647965fb3738654e6962eb8b58b0c2a84271655b4d748836 + languageName: node + linkType: hard + "hast-util-to-jsx-runtime@npm:^2.0.0": version: 2.3.2 resolution: "hast-util-to-jsx-runtime@npm:2.3.2" @@ -31854,6 +32465,29 @@ __metadata: languageName: node linkType: hard +"hast-util-to-jsx-runtime@npm:^2.3.6": + version: 2.3.6 + resolution: "hast-util-to-jsx-runtime@npm:2.3.6" + dependencies: + "@types/estree": "npm:^1.0.0" + "@types/hast": "npm:^3.0.0" + "@types/unist": "npm:^3.0.0" + comma-separated-tokens: "npm:^2.0.0" + devlop: "npm:^1.0.0" + estree-util-is-identifier-name: "npm:^3.0.0" + hast-util-whitespace: "npm:^3.0.0" + mdast-util-mdx-expression: "npm:^2.0.0" + mdast-util-mdx-jsx: "npm:^3.0.0" + mdast-util-mdxjs-esm: "npm:^2.0.0" + property-information: "npm:^7.0.0" + space-separated-tokens: "npm:^2.0.0" + style-to-js: "npm:^1.0.0" + unist-util-position: "npm:^5.0.0" + vfile-message: "npm:^4.0.0" + checksum: 10c0/27297e02848fe37ef219be04a26ce708d17278a175a807689e94a821dcffc88aa506d62c3a85beed1f9a8544f7211bdcbcde0528b7b456a57c2e342c3fd11056 + languageName: node + linkType: hard + "hast-util-whitespace@npm:^3.0.0": version: 3.0.0 resolution: "hast-util-whitespace@npm:3.0.0" @@ -32211,6 +32845,13 @@ __metadata: languageName: node linkType: hard +"html-void-elements@npm:^3.0.0": + version: 3.0.0 + resolution: "html-void-elements@npm:3.0.0" + checksum: 10c0/a8b9ec5db23b7c8053876dad73a0336183e6162bf6d2677376d8b38d654fdc59ba74fdd12f8812688f7db6fad451210c91b300e472afc0909224e0a44c8610d2 + languageName: node + linkType: hard + "html-webpack-plugin@npm:5.6.4": version: 5.6.4 resolution: "html-webpack-plugin@npm:5.6.4" @@ -32768,6 +33409,13 @@ __metadata: languageName: node linkType: hard +"inline-style-parser@npm:0.2.7": + version: 0.2.7 + resolution: "inline-style-parser@npm:0.2.7" + checksum: 10c0/d884d76f84959517430ae6c22f0bda59bb3f58f539f99aac75a8d786199ec594ed648c6ab4640531f9fc244b0ed5cd8c458078e592d016ef06de793beb1debff + languageName: node + linkType: hard + "inquirer@npm:8.2.7, inquirer@npm:^8.0.0": version: 8.2.7 resolution: "inquirer@npm:8.2.7" @@ -35794,6 +36442,15 @@ __metadata: languageName: node linkType: hard +"lucide-react@npm:^0.522.0": + version: 0.522.0 + resolution: "lucide-react@npm:0.522.0" + peerDependencies: + react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0 + checksum: 10c0/92f18da5ade753c7955a3d0fe3779b62831bf1d6ab15396b6024ef66efe7df7b78e19728e3cf59d1bd01bbee16de0c474a5d6b2741e6b5c97d8374d02f776898 + languageName: node + linkType: hard + "luxon@npm:^3.2.1": version: 3.5.0 resolution: "luxon@npm:3.5.0" @@ -38511,6 +39168,17 @@ __metadata: languageName: node linkType: hard +"oniguruma-to-es@npm:^2.2.0": + version: 2.3.0 + resolution: "oniguruma-to-es@npm:2.3.0" + dependencies: + emoji-regex-xs: "npm:^1.0.0" + regex: "npm:^5.1.1" + regex-recursion: "npm:^5.1.1" + checksum: 10c0/57ad95f3e9a50be75e7d54e582d8d4da4003f983fd04d99ccc9d17d2dc04e30ea64126782f2e758566bcef2c4c55db0d6a3d344f35ca179dd92ea5ca92fc0313 + languageName: node + linkType: hard + "onnx-proto@npm:^4.0.4": version: 4.0.4 resolution: "onnx-proto@npm:4.0.4" @@ -40431,6 +41099,13 @@ __metadata: languageName: node linkType: hard +"property-information@npm:^7.0.0": + version: 7.1.0 + resolution: "property-information@npm:7.1.0" + checksum: 10c0/e0fe22cff26103260ad0e82959229106563fa115a54c4d6c183f49d88054e489cc9f23452d3ad584179dc13a8b7b37411a5df873746b5e4086c865874bfa968e + languageName: node + linkType: hard + "prosemirror-collab@npm:1.3.0": version: 1.3.0 resolution: "prosemirror-collab@npm:1.3.0" @@ -41451,6 +42126,22 @@ __metadata: languageName: node linkType: hard +"react-router@npm:7.10.1": + version: 7.10.1 + resolution: "react-router@npm:7.10.1" + dependencies: + cookie: "npm:^1.0.1" + set-cookie-parser: "npm:^2.6.0" + peerDependencies: + react: ">=18" + react-dom: ">=18" + peerDependenciesMeta: + react-dom: + optional: true + checksum: 10c0/e114a319603ccf0394f616f954ee3f53bec04636a2f13383b1e941b8fa6c1c64b71b60527e3db8e7f971dcfaaeb9a82bd7c2ddd884a718694e589403e6975d52 + languageName: node + linkType: hard + "react-style-singleton@npm:^2.2.1": version: 2.2.1 resolution: "react-style-singleton@npm:2.2.1" @@ -41913,6 +42604,32 @@ __metadata: languageName: node linkType: hard +"regex-recursion@npm:^5.1.1": + version: 5.1.1 + resolution: "regex-recursion@npm:5.1.1" + dependencies: + regex: "npm:^5.1.1" + regex-utilities: "npm:^2.3.0" + checksum: 10c0/c61c284bc41f2b271dfa0549d657a5a26397108b860d7cdb15b43080196681c0092bf8cf920a8836213e239d1195c4ccf6db9be9298bce4e68c9daab1febeab9 + languageName: node + linkType: hard + +"regex-utilities@npm:^2.3.0": + version: 2.3.0 + resolution: "regex-utilities@npm:2.3.0" + checksum: 10c0/78c550a80a0af75223244fff006743922591bd8f61d91fef7c86b9b56cf9bbf8ee5d7adb6d8991b5e304c57c90103fc4818cf1e357b11c6c669b782839bd7893 + languageName: node + linkType: hard + +"regex@npm:^5.1.1": + version: 5.1.1 + resolution: "regex@npm:5.1.1" + dependencies: + regex-utilities: "npm:^2.3.0" + checksum: 10c0/314e032f0fe09497ce7a160b99675c4a16c7524f0a24833f567cbbf3a2bebc26bf59737dc5c23f32af7c74aa7a6bd3f809fc72c90c49a05faf8be45677db508a + languageName: node + linkType: hard + "regexp-ast-analysis@npm:^0.7.0, regexp-ast-analysis@npm:^0.7.1": version: 0.7.1 resolution: "regexp-ast-analysis@npm:0.7.1" @@ -42586,6 +43303,87 @@ __metadata: languageName: node linkType: hard +"rollup@npm:^4.40.0": + version: 4.54.0 + resolution: "rollup@npm:4.54.0" + dependencies: + "@rollup/rollup-android-arm-eabi": "npm:4.54.0" + "@rollup/rollup-android-arm64": "npm:4.54.0" + "@rollup/rollup-darwin-arm64": "npm:4.54.0" + "@rollup/rollup-darwin-x64": "npm:4.54.0" + "@rollup/rollup-freebsd-arm64": "npm:4.54.0" + "@rollup/rollup-freebsd-x64": "npm:4.54.0" + "@rollup/rollup-linux-arm-gnueabihf": "npm:4.54.0" + "@rollup/rollup-linux-arm-musleabihf": "npm:4.54.0" + "@rollup/rollup-linux-arm64-gnu": "npm:4.54.0" + "@rollup/rollup-linux-arm64-musl": "npm:4.54.0" + "@rollup/rollup-linux-loong64-gnu": "npm:4.54.0" + "@rollup/rollup-linux-ppc64-gnu": "npm:4.54.0" + "@rollup/rollup-linux-riscv64-gnu": "npm:4.54.0" + "@rollup/rollup-linux-riscv64-musl": "npm:4.54.0" + "@rollup/rollup-linux-s390x-gnu": "npm:4.54.0" + "@rollup/rollup-linux-x64-gnu": "npm:4.54.0" + "@rollup/rollup-linux-x64-musl": "npm:4.54.0" + "@rollup/rollup-openharmony-arm64": "npm:4.54.0" + "@rollup/rollup-win32-arm64-msvc": "npm:4.54.0" + "@rollup/rollup-win32-ia32-msvc": "npm:4.54.0" + "@rollup/rollup-win32-x64-gnu": "npm:4.54.0" + "@rollup/rollup-win32-x64-msvc": "npm:4.54.0" + "@types/estree": "npm:1.0.8" + fsevents: "npm:~2.3.2" + dependenciesMeta: + "@rollup/rollup-android-arm-eabi": + optional: true + "@rollup/rollup-android-arm64": + optional: true + "@rollup/rollup-darwin-arm64": + optional: true + "@rollup/rollup-darwin-x64": + optional: true + "@rollup/rollup-freebsd-arm64": + optional: true + "@rollup/rollup-freebsd-x64": + optional: true + "@rollup/rollup-linux-arm-gnueabihf": + optional: true + "@rollup/rollup-linux-arm-musleabihf": + optional: true + "@rollup/rollup-linux-arm64-gnu": + optional: true + "@rollup/rollup-linux-arm64-musl": + optional: true + "@rollup/rollup-linux-loong64-gnu": + optional: true + "@rollup/rollup-linux-ppc64-gnu": + optional: true + "@rollup/rollup-linux-riscv64-gnu": + optional: true + "@rollup/rollup-linux-riscv64-musl": + optional: true + "@rollup/rollup-linux-s390x-gnu": + optional: true + "@rollup/rollup-linux-x64-gnu": + optional: true + "@rollup/rollup-linux-x64-musl": + optional: true + "@rollup/rollup-openharmony-arm64": + optional: true + "@rollup/rollup-win32-arm64-msvc": + optional: true + "@rollup/rollup-win32-ia32-msvc": + optional: true + "@rollup/rollup-win32-x64-gnu": + optional: true + "@rollup/rollup-win32-x64-msvc": + optional: true + fsevents: + optional: true + bin: + rollup: dist/bin/rollup + checksum: 10c0/62e5fd5d43e72751ac631f13fd7e70bec0fc3809231d5e087c3c0811945e7b8f0956620c5bed4e0cd67085325324266989e5ea4d22985c2677119ac7809b6455 + languageName: node + linkType: hard + "rollup@npm:~4.50.2": version: 4.50.2 resolution: "rollup@npm:4.50.2" @@ -43189,6 +43987,13 @@ __metadata: languageName: node linkType: hard +"set-cookie-parser@npm:^2.6.0": + version: 2.7.2 + resolution: "set-cookie-parser@npm:2.7.2" + checksum: 10c0/4381a9eb7ee951dfe393fe7aacf76b9a3b4e93a684d2162ab35594fa4053cc82a4d7d7582bf397718012c9adcf839b8cd8f57c6c42901ea9effe33c752da4a45 + languageName: node + linkType: hard + "set-cookie-parser@npm:~2.7.0": version: 2.7.1 resolution: "set-cookie-parser@npm:2.7.1" @@ -43504,6 +44309,22 @@ __metadata: languageName: node linkType: hard +"shiki@npm:^1.29.2": + version: 1.29.2 + resolution: "shiki@npm:1.29.2" + dependencies: + "@shikijs/core": "npm:1.29.2" + "@shikijs/engine-javascript": "npm:1.29.2" + "@shikijs/engine-oniguruma": "npm:1.29.2" + "@shikijs/langs": "npm:1.29.2" + "@shikijs/themes": "npm:1.29.2" + "@shikijs/types": "npm:1.29.2" + "@shikijs/vscode-textmate": "npm:^10.0.1" + "@types/hast": "npm:^3.0.4" + checksum: 10c0/9ef452021582c405501077082c4ae8d877027dca6488d2c7a1963ed661567f121b4cc5dea9dfab26689504b612b8a961f3767805cbeaaae3c1d6faa5e6f37eb0 + languageName: node + linkType: hard + "short-unique-id@npm:^5.2.0": version: 5.2.0 resolution: "short-unique-id@npm:5.2.0" @@ -44748,6 +45569,24 @@ __metadata: languageName: node linkType: hard +"style-to-js@npm:^1.0.0": + version: 1.1.21 + resolution: "style-to-js@npm:1.1.21" + dependencies: + style-to-object: "npm:1.0.14" + checksum: 10c0/94231aa80f58f442c3a5ae01a21d10701e5d62f96b4b3e52eab3499077ee52df203cc0df4a1a870707f5e99470859136ea8657b782a5f4ca7934e0ffe662a588 + languageName: node + linkType: hard + +"style-to-object@npm:1.0.14": + version: 1.0.14 + resolution: "style-to-object@npm:1.0.14" + dependencies: + inline-style-parser: "npm:0.2.7" + checksum: 10c0/854d9e9b77afc336e6d7b09348e7939f2617b34eb0895824b066d8cd1790284cb6d8b2ba36be88025b2595d715dba14b299ae76e4628a366541106f639e13679 + languageName: node + linkType: hard + "style-to-object@npm:^1.0.0": version: 1.0.8 resolution: "style-to-object@npm:1.0.8" @@ -44902,6 +45741,18 @@ __metadata: languageName: node linkType: hard +"swr@npm:^2.2.5": + version: 2.3.8 + resolution: "swr@npm:2.3.8" + dependencies: + dequal: "npm:^2.0.3" + use-sync-external-store: "npm:^1.6.0" + peerDependencies: + react: ^16.11.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 + checksum: 10c0/ee879100fc14a9d3a9f453842cb838027f3eba728e1b33be4998eea2f612d4822a5f70815c64cceb554ba36d9120fe3d7fed63597642823f204752750208fd8e + languageName: node + linkType: hard + "sylvester@npm:>= 0.0.8": version: 0.0.21 resolution: "sylvester@npm:0.0.21" @@ -44980,6 +45831,13 @@ __metadata: languageName: node linkType: hard +"tailwind-merge@npm:^3.3.1": + version: 3.4.0 + resolution: "tailwind-merge@npm:3.4.0" + checksum: 10c0/eaf17bb695c51c7bb7a90366a9c62be295473ee97fcfd1da54287714d4a5788a88ff4ad1ab9e0128638257fda777d6c9ea88682e36195e31a7fa2cf43f45e310 + languageName: node + linkType: hard + "tapable@npm:^2.0.0, tapable@npm:^2.2.0, tapable@npm:^2.2.1, tapable@npm:^2.3.0": version: 2.3.0 resolution: "tapable@npm:2.3.0" @@ -45247,6 +46105,13 @@ __metadata: languageName: node linkType: hard +"throttleit@npm:2.1.0": + version: 2.1.0 + resolution: "throttleit@npm:2.1.0" + checksum: 10c0/1696ae849522cea6ba4f4f3beac1f6655d335e51b42d99215e196a718adced0069e48deaaf77f7e89f526ab31de5b5c91016027da182438e6f9280be2f3d5265 + languageName: node + linkType: hard + "through2@npm:^3.0.1": version: 3.0.2 resolution: "through2@npm:3.0.2" @@ -46883,7 +47748,7 @@ __metadata: languageName: node linkType: hard -"use-sync-external-store@npm:^1.4.0": +"use-sync-external-store@npm:^1.4.0, use-sync-external-store@npm:^1.6.0": version: 1.6.0 resolution: "use-sync-external-store@npm:1.6.0" peerDependencies: @@ -47106,6 +47971,61 @@ __metadata: languageName: node linkType: hard +"vite@npm:7.0.7": + version: 7.0.7 + resolution: "vite@npm:7.0.7" + dependencies: + esbuild: "npm:^0.25.0" + fdir: "npm:^6.4.6" + fsevents: "npm:~2.3.3" + picomatch: "npm:^4.0.3" + postcss: "npm:^8.5.6" + rollup: "npm:^4.40.0" + tinyglobby: "npm:^0.2.14" + peerDependencies: + "@types/node": ^20.19.0 || >=22.12.0 + jiti: ">=1.21.0" + less: ^4.0.0 + lightningcss: ^1.21.0 + sass: ^1.70.0 + sass-embedded: ^1.70.0 + stylus: ">=0.54.8" + sugarss: ^5.0.0 + terser: ^5.16.0 + tsx: ^4.8.1 + yaml: ^2.4.2 + dependenciesMeta: + fsevents: + optional: true + peerDependenciesMeta: + "@types/node": + optional: true + jiti: + optional: true + less: + optional: true + lightningcss: + optional: true + sass: + optional: true + sass-embedded: + optional: true + stylus: + optional: true + sugarss: + optional: true + terser: + optional: true + tsx: + optional: true + yaml: + optional: true + bin: + vite: bin/vite.js + checksum: 10c0/ccede60fced8a738f10c804a47d82b551a4250114ceb3026dc65a7ef8ba4700154ad59a85674862271a53eecc3c300bfe4d41672ae26212d9f0a99fb995344fc + languageName: node + linkType: hard + "vite@npm:7.1.11": version: 7.1.11 resolution: "vite@npm:7.1.11" @@ -48699,14 +49619,14 @@ __metadata: languageName: node linkType: hard -"zod@npm:^3.22.4 || ^4.0.0, zod@npm:^3.25 || ^4.0, zod@npm:^3.25.0 || ^4.0.0, zod@npm:^4.0.17": +"zod@npm:^3.22.4 || ^4.0.0, zod@npm:^3.25 || ^4.0, zod@npm:^4.0.17": version: 4.1.13 resolution: "zod@npm:4.1.13" checksum: 10c0/d7e74e82dba81a91ffc3239cd85bc034abe193a28f7087a94ab258a3e48e9a7ca4141920cac979a0d781495b48fc547777394149f26be04c3dc642f58bbc3941 languageName: node linkType: hard -"zod@npm:^3.23.8, zod@npm:^3.24.2, zod@npm:^3.25.76": +"zod@npm:^3.23.8, zod@npm:^3.24.2": version: 3.25.76 resolution: "zod@npm:3.25.76" checksum: 10c0/5718ec35e3c40b600316c5b4c5e4976f7fee68151bc8f8d90ec18a469be9571f072e1bbaace10f1e85cf8892ea12d90821b200e980ab46916a6166a4260a983c @@ -48763,7 +49683,7 @@ __metadata: languageName: node linkType: hard -"zwitch@npm:^2.0.0": +"zwitch@npm:^2.0.0, zwitch@npm:^2.0.4": version: 2.0.4 resolution: "zwitch@npm:2.0.4" checksum: 10c0/3c7830cdd3378667e058ffdb4cf2bb78ac5711214e2725900873accb23f3dfe5f9e7e5a06dcdc5f29605da976fc45c26d9a13ca334d6eea2245a15e77b8fc06e From 12d1dde1d4a8d87930e61860e7ea4ebbf5e5ca89 Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Mon, 22 Dec 2025 18:00:13 +0100 Subject: [PATCH 15/16] cleanups --- .markdownlint-cli2.jsonc | 2 +- .../_ai/wiki/deployment-requirements.md | 1 + .../_ai/wiki/gaps-and-next-steps.md | 18 ++++++ .../hash-ai-agent/_ai/wiki/handoff-packets.md | 1 + .../_ai/wiki/harness-patterns.md | 1 + .../hash-ai-agent/_ai/wiki/mastra-patterns.md | 29 +++++++++ apps/hash-ai-agent/package.json | 2 +- apps/hash-ai-agent/src/client/README.md | 20 +++--- .../entity-schemas/organization.bundled.json | 4 +- .../organization.dereferenced.json | 4 +- yarn.lock | 61 ++----------------- 11 files changed, 72 insertions(+), 71 deletions(-) diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index 96992a44bce..0ca56ef7917 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -30,6 +30,6 @@ "node_modules/**", "target/**", "**/_temp/**", - "**/agent/**" + "**/_ai/**" ] } diff --git a/apps/hash-ai-agent/_ai/wiki/deployment-requirements.md b/apps/hash-ai-agent/_ai/wiki/deployment-requirements.md index 369e1796934..b18d4e58741 100644 --- a/apps/hash-ai-agent/_ai/wiki/deployment-requirements.md +++ b/apps/hash-ai-agent/_ai/wiki/deployment-requirements.md @@ -38,6 +38,7 @@ const mastra = new Mastra({ ``` ### Supported Backends + - **PostgreSQL** - production recommended - **LibSQL/SQLite** - local development, serverless edge - **Custom** - implement `BaseStorage` interface diff --git a/apps/hash-ai-agent/_ai/wiki/gaps-and-next-steps.md b/apps/hash-ai-agent/_ai/wiki/gaps-and-next-steps.md index 1d1d340af31..c7ca1ba20e5 100644 --- a/apps/hash-ai-agent/_ai/wiki/gaps-and-next-steps.md +++ b/apps/hash-ai-agent/_ai/wiki/gaps-and-next-steps.md @@ -6,6 +6,7 @@ ## Current State Summary The planning framework has: + - ✅ PlanSpec schema with 4 step types (research, synthesize, experiment, develop) - ✅ Plan validation (structural checks) - ✅ Deterministic scorers (structure, coverage, rigor, unknowns) @@ -46,11 +47,13 @@ These represent a shift toward **epistemically rigorous R&D orchestration** rath **Problem**: Current step outputs are unstructured (`outputs: DataContract[]` at plan-time, arbitrary objects at runtime). No standard for what constitutes a "complete" step contribution. **Solution**: Implement `StepHandoff` schema as the canonical output format: + - Every step produces: attempted, observed, changed, notDone, highestImpactUncertainty, nextAgentShouldFirst - Handoff completeness becomes the stop condition - Handoffs fold into execution state **Files to modify**: + - `schemas/plan-spec.ts` — Add `zStepHandoff` and related types - `tools/plan-compiler.ts` — Update prompt building to require handoff format - `tools/mock-agent.ts` — Return handoff-shaped mock responses @@ -64,12 +67,14 @@ These represent a shift toward **epistemically rigorous R&D orchestration** rath **Problem**: No structured runtime state beyond what Mastra provides. Can't track evidence accumulation, uncertainty evolution, or audit trail across steps. **Solution**: Implement `ExecutionState` as described in [execution-state.md](./execution-state.md): + - Initialize from PlanSpec - Fold handoffs after each step - Track evidence ledger, uncertainty inventory, artifact registry, gaps registry - Enable re-planning triggers **Files to create/modify**: + - `schemas/execution-state.ts` — New schema - `tools/plan-compiler.ts` or new `tools/interpreter.ts` — State management @@ -84,6 +89,7 @@ These represent a shift toward **epistemically rigorous R&D orchestration** rath **Insight**: Need a middle ground between deterministic mocks and real long-running execution. **Solution**: "Synthetic mocking" — mock agents that make real LLM calls to generate realistic but synthetic step outputs: + - Takes step context (type, description, inputs) - Generates plausible handoff packet via LLM - Can simulate failures, unexpected findings, or re-planning triggers @@ -98,6 +104,7 @@ interface SyntheticMockConfig { ``` **Files to modify**: + - `tools/mock-agent.ts` — Add synthetic mode with LLM-backed generation **Complexity**: Low-Medium @@ -109,6 +116,7 @@ interface SyntheticMockConfig { **Problem**: Compiled workflows have fixed shape at commit time. Can't support Level 3 dynamism (re-planning based on execution outcomes). **Solution**: Implement interpreter pattern as described in [execution-state.md](./execution-state.md): + ```typescript createWorkflow(...) .map(initializeExecutionState) @@ -123,6 +131,7 @@ createWorkflow(...) ``` The interpreter step: + - Picks next ready step(s) from topology - Builds context from prior handoffs - Executes step, expecting handoff output @@ -130,6 +139,7 @@ The interpreter step: - Checks re-planning triggers **Files to create**: + - `workflows/interpreted-execution.ts` — New interpreter-based execution workflow - Could coexist with compiled approach for simpler plans @@ -142,11 +152,13 @@ The interpreter step: **Problem**: Revision loop only checks boolean `valid` flag. Structurally valid but mediocre plans pass immediately. **Solution**: Add composite score threshold to revision loop: + - After validation passes, run `scorePlanComposite()` - Require `overall >= 0.85` (configurable) to exit loop - If below threshold, build feedback from low-scoring areas **Files to modify**: + - `workflows/planning-workflow.ts` — Integrate scorer into loop condition **Complexity**: Low @@ -158,11 +170,13 @@ The interpreter step: **Problem**: No semantic review of plans against original goal. Validation is structural only. **Solution**: Implement supervisor agent as LLM approval gate: + - Reviews plan against goal - Returns `{ approved: boolean, feedback?: string, issues?: string[] }` - Integrates after validation + scoring in revision loop **Files to create**: + - `agents/supervisor-agent.ts` **Complexity**: Medium @@ -174,6 +188,7 @@ The interpreter step: **Problem**: No support for human approval checkpoints during execution. **Solution**: Use Mastra's `suspend()`/`resume()` at key decision points: + - Post-design, pre-execution (human approves experimental design) - Post-analysis, pre-interpretation (human validates analysis) - Post-conclusion, pre-propagation (human checks confidence claims) @@ -187,10 +202,13 @@ The interpreter step: ## Deferred / Low Priority ### Conditional Branching (Level 1 Dynamism) + Static branching based on conditions in plan. Design options captured in [conditional-branching.md](./conditional-branching.md). Less urgent now that interpreter pattern handles higher levels of dynamism. ### Real Agent Execution + Replacing mock agents with actual capable agents. Deferred until: + 1. Handoff packet format is stable 2. Execution state management is solid 3. Quality of plan decomposition is validated diff --git a/apps/hash-ai-agent/_ai/wiki/handoff-packets.md b/apps/hash-ai-agent/_ai/wiki/handoff-packets.md index 5c4a336afd3..316efa0ebae 100644 --- a/apps/hash-ai-agent/_ai/wiki/handoff-packets.md +++ b/apps/hash-ai-agent/_ai/wiki/handoff-packets.md @@ -92,6 +92,7 @@ The `outputs` field describes *intent*; the handoff describes *actuality*. Orche ### Execution State Accumulation Handoffs accumulate into execution state, enabling: + - Evidence ledger updates (from `observed` entries) - Uncertainty inventory updates (from `highestImpactUncertainty`) - Artifact tracking (from `changed` entries) diff --git a/apps/hash-ai-agent/_ai/wiki/harness-patterns.md b/apps/hash-ai-agent/_ai/wiki/harness-patterns.md index d6fd4b34e02..b45c8243cba 100644 --- a/apps/hash-ai-agent/_ai/wiki/harness-patterns.md +++ b/apps/hash-ai-agent/_ai/wiki/harness-patterns.md @@ -1,4 +1,5 @@ > Essential architectural patterns from Anthropic’s two articles re agent harnesses: +> > - https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents > - https://www.anthropic.com/research/building-effective-agents diff --git a/apps/hash-ai-agent/_ai/wiki/mastra-patterns.md b/apps/hash-ai-agent/_ai/wiki/mastra-patterns.md index dc48a60a701..c70721e63d6 100644 --- a/apps/hash-ai-agent/_ai/wiki/mastra-patterns.md +++ b/apps/hash-ai-agent/_ai/wiki/mastra-patterns.md @@ -1,7 +1,9 @@ ## Mastra: Agent Framework for Production ### Workflow Orchestration + Mastra's core strength is **graph-based workflows** with: + - `.then()`, `.branch()`, `.parallel()` for step composition - **Suspend/resume**: Pause workflows for human-in-the-loop (HITL), external callbacks, or rate limiting - **Event-driven execution**: `.waitForEvent()`, `.sendEvent()` for async triggers @@ -9,7 +11,9 @@ Mastra's core strength is **graph-based workflows** with: Neither TanStack AI nor Vercel AI SDK have workflow engines—they focus on chat/agent loops. ### Human-in-the-Loop (HITL) + Workflows can **suspend at any step**, persist state to storage (LibSQL/PostgreSQL), and resume later: + ```typescript execute: async ({ inputData, resumeData, suspend }) => { const { approved } = resumeData ?? {} @@ -19,10 +23,13 @@ execute: async ({ inputData, resumeData, suspend }) => { return { output: `${message} - Deleted` } } ``` + State persists across deployments and server restarts. TanStack AI has tool approval but no workflow suspension. Vercel AI SDK relies on external state management. ### Memory Systems + Mastra provides **working memory** and **semantic recall** with storage backends (PostgreSQL, LibSQL, Upstash). Agents remember conversation history across sessions: + ```typescript const agent = new Agent({ memory: new Memory({ @@ -30,10 +37,13 @@ const agent = new Agent({ }) }) ``` + TanStack AI and Vercel AI SDK require manual memory implementation. ### RAG Support + Built-in **document processing, chunking, embeddings, and vector search** with: + - `MDocument.fromText()` for document ingestion - Chunking strategies (recursive, sliding window) - Vector store integrations (pgvector, Pinecone, Qdrant, MongoDB) @@ -41,14 +51,18 @@ Built-in **document processing, chunking, embeddings, and vector search** with: Neither TanStack AI nor Vercel AI SDK provide RAG primitives—use external libraries like LangChain or LlamaIndex. ### Agents vs. Workflows + Mastra distinguishes **agents** (autonomous, LLM-driven reasoning) from **workflows** (deterministic step sequences): + - **Agents**: Use `maxSteps` for iteration limits, call tools dynamically based on LLM reasoning - **Workflows**: Explicit control flow with fixed steps, branches, and parallel execution Vercel AI SDK and TanStack AI focus on agents (agentic loops), not deterministic workflows. ### Deployment Options + Mastra offers: + - **Mastra Cloud**: Fully managed, GitHub integration, auto-deploy on push, built-in observability - **Self-hosted**: Node.js server, custom middleware, integrates with Next.js/Express/Hono - **Serverless**: Vercel, Netlify, Cloudflare Workers @@ -56,19 +70,24 @@ Mastra offers: TanStack AI and Vercel AI SDK are libraries, not platforms—deployment is your responsibility. ### Observability + Comprehensive tracing via **OpenTelemetry** with exporters for: + - Mastra Cloud (centralized dashboard) - Langfuse, Datadog, Sentry, Axiom Traces show agent/workflow execution, token usage, tool calls, and errors. ### Integration with Vercel AI SDK + Mastra **integrates with Vercel AI SDK UI**. Use `useChat()` hook to call Mastra agents: + ```typescript const { messages, sendMessage } = useChat({ transport: new DefaultChatTransport({ api: 'http://localhost:4111/chat' }) }) ``` + This lets you combine Mastra's backend orchestration with Vercel's frontend tooling. *** @@ -97,6 +116,7 @@ This lets you combine Mastra's backend orchestration with Vercel's frontend tool ## Critical Assessment ### TanStack AI Strengths + - **Isomorphic tools**: Cleanest API for shared tool definitions between server/client - **Type safety**: Provider-specific options are typed per model - **DevTools**: Real-time inspection from day one @@ -104,6 +124,7 @@ This lets you combine Mastra's backend orchestration with Vercel's frontend tool - **No vendor lock-in**: Open protocols, multiple adapters ### TanStack AI Weaknesses + - **Alpha stage**: Missing features (structured outputs, speech APIs, more providers) - **Small ecosystem**: Fewer adapters, integrations, and community resources vs. Vercel AI SDK - **Sparse docs**: Advanced patterns (custom streaming, complex agent flows) underdocumented @@ -111,6 +132,7 @@ This lets you combine Mastra's backend orchestration with Vercel's frontend tool - **No memory/RAG**: Requires external libraries ### Vercel AI SDK Strengths + - **Mature**: Stable v5 with 40+ providers, extensive docs, large community - **Feature-rich**: Structured outputs, speech APIs, MCP, RSC, transport flexibility - **Agentic control**: `stopWhen` + `prepareStep` for fine-grained agent loops @@ -118,6 +140,7 @@ This lets you combine Mastra's backend orchestration with Vercel's frontend tool - **Production-ready**: Used by thousands of apps on Vercel ### Vercel AI SDK Weaknesses + - **No isomorphic tools**: Separate server/client implementations - **Type safety gaps**: Provider options not strongly typed - **No devtools**: Relies on third-party observability (Datadog, Axiom) @@ -125,6 +148,7 @@ This lets you combine Mastra's backend orchestration with Vercel's frontend tool - **Vercel optimization**: Best DX on Vercel platform (edge caching, streaming) ### Mastra Strengths + - **Workflow orchestration**: Graph-based, suspend/resume, event-driven - **HITL**: Pause workflows for approvals, persist state across deployments - **Memory & RAG**: Built-in storage, document processing, vector search @@ -132,6 +156,7 @@ This lets you combine Mastra's backend orchestration with Vercel's frontend tool - **Agent + Workflow**: Combine autonomous agents with deterministic workflows ### Mastra Weaknesses + - **Heavy**: `@mastra/core` is 1000+ files, 10MB, 43 dependencies - **TypeScript-only**: No Python/PHP support (unlike TanStack AI's roadmap) - **Node.js-focused**: Best on Next.js/React, less suited for other frameworks @@ -143,6 +168,7 @@ This lets you combine Mastra's backend orchestration with Vercel's frontend tool ## Use Case Recommendations ### Choose **TanStack AI** if: + - You need **framework-agnostic** AI (Vue, Svelte, Solid, vanilla JS) - **Isomorphic tools** (single definition, server/client implementations) are critical - You want **per-model type safety** for provider options @@ -150,6 +176,7 @@ This lets you combine Mastra's backend orchestration with Vercel's frontend tool - You're willing to adopt **alpha software** and contribute to a new ecosystem ### Choose **Vercel AI SDK** if: + - You need **production-ready** features (structured outputs, speech APIs, 40+ providers) - **Fine-grained agent control** (`stopWhen`, `prepareStep`) is required - You're building in **Next.js/React** and want seamless `useChat` integration @@ -157,6 +184,7 @@ This lets you combine Mastra's backend orchestration with Vercel's frontend tool - You prefer **mature ecosystem** with extensive docs and community support ### Choose **Mastra** if: + - You need **workflow orchestration** (branching, parallel steps, suspend/resume) - **Human-in-the-loop** with persistent state is critical - **Memory systems** and **RAG** are required out-of-the-box @@ -174,6 +202,7 @@ This lets you combine Mastra's backend orchestration with Vercel's frontend tool **Mastra** prioritizes **orchestration complexity**: workflows, HITL, memory, RAG. It's the "enterprise backbone"—built for multi-step agent systems with observability and persistence. The trade-off? Heavy dependencies, Node.js focus, steeper learning curve. ### Terse Summary + - **TanStack AI**: Framework-agnostic, isomorphic tools, type-safe provider options, built-in devtools, alpha stage (missing structured outputs, 40+ providers) - **Vercel AI SDK**: Production-ready, 40+ providers, structured outputs, fine-grained agent control (`stopWhen`/`prepareStep`), React/Next.js optimized, no isomorphic tools - **Mastra**: Workflow orchestration (suspend/resume, HITL), memory + RAG built-in, agent + workflow hybrid, production observability (Mastra Cloud), heavy (10MB, Node.js-focused) diff --git a/apps/hash-ai-agent/package.json b/apps/hash-ai-agent/package.json index 4596dc5c92e..75ac1a596d5 100644 --- a/apps/hash-ai-agent/package.json +++ b/apps/hash-ai-agent/package.json @@ -11,8 +11,8 @@ "codegen": "tsx src/mastra/fixtures/generate-schemas.ts", "demo:plan": "tsx src/mastra/scripts/demo-plan-execution.ts", "dev": "concurrently --names mastra,client --prefix-colors blue,green \"yarn dev:mastra\" \"yarn dev:client\"", - "dev:mastra": "mastra dev", "dev:client": "vite --config src/client/vite.config.ts", + "dev:mastra": "mastra dev", "eval": "RUN_LLM_SCORERS=true vitest run", "eval:dev": "RUN_LLM_SCORERS=true vitest dev", "fix": "npm-run-all --continue-on-error \"fix:*\"", diff --git a/apps/hash-ai-agent/src/client/README.md b/apps/hash-ai-agent/src/client/README.md index b18451dff63..ab6db38ef78 100644 --- a/apps/hash-ai-agent/src/client/README.md +++ b/apps/hash-ai-agent/src/client/README.md @@ -6,7 +6,7 @@ A minimal React chat frontend that connects to the Mastra backend server. This setup runs **two separate processes**: -``` +```txt ┌─────────────────────┐ ┌─────────────────────┐ │ Vite Dev Server │ │ Mastra Server │ │ (port 5173) │ ──────▶ │ (port 4111) │ @@ -40,7 +40,7 @@ Open http://localhost:5173 to use the chat interface. ## Key Files -``` +```txt src/ ├── mastra/ # Mastra server (agents, workflows) │ └── index.ts # Mastra config with chatRoute() @@ -103,18 +103,19 @@ function Chat() { During development, Vite proxies `/chat/*` and `/api/*` requests to the Mastra server. This avoids CORS issues by making requests same-origin from the browser's perspective. For production, you have two options: + 1. Configure your production server to proxy requests similarly 2. Set appropriate CORS headers on the Mastra server ## Packages Used -| Package | Purpose | -|---------|---------| +| Package | Purpose | +| ---------------- | ----------------------------------------- | | `@mastra/ai-sdk` | `chatRoute()` helper for AI SDK streaming | -| `@ai-sdk/react` | `useChat()` hook for client-side chat | -| `ai` | Vercel AI SDK core (DefaultChatTransport) | -| `react-router` | Client-side routing | -| `vite` | Dev server with HMR and proxy | +| `@ai-sdk/react` | `useChat()` hook for client-side chat | +| `ai` | Vercel AI SDK core (DefaultChatTransport) | +| `react-router` | Client-side routing | +| `vite` | Dev server with HMR and proxy | ## Adding More Features @@ -176,13 +177,16 @@ function MyComponent() { ## Troubleshooting ### "Failed to fetch" or Network Errors + - Ensure Mastra server is running (`yarn dev:mastra`) - Check that port 4111 is not in use by another process ### Agent Not Found + - Verify the agent ID matches one registered in `src/mastra/index.ts` - Check Mastra server logs for errors ### CORS Errors in Production + - Configure CORS in Mastra server config: `server.cors.origin` - Or set up a reverse proxy in your production infrastructure diff --git a/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.bundled.json b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.bundled.json index ba18632b785..88f4d6b5538 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.bundled.json +++ b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.bundled.json @@ -677,8 +677,8 @@ } }, "required": [ - "https://hash.ai/@h/types/property-type/organization-name/", - "https://hash.ai/@h/types/property-type/shortname/" + "https://hash.ai/@h/types/property-type/shortname/", + "https://hash.ai/@h/types/property-type/organization-name/" ], "title": "Organization", "type": "object" diff --git a/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.dereferenced.json b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.dereferenced.json index 95369b81315..4a3fdc93397 100644 --- a/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.dereferenced.json +++ b/apps/hash-ai-agent/src/mastra/fixtures/entity-schemas/organization.dereferenced.json @@ -1155,8 +1155,8 @@ } }, "required": [ - "https://hash.ai/@h/types/property-type/organization-name/", - "https://hash.ai/@h/types/property-type/shortname/" + "https://hash.ai/@h/types/property-type/shortname/", + "https://hash.ai/@h/types/property-type/organization-name/" ], "title": "Organization", "type": "object" diff --git a/yarn.lock b/yarn.lock index 99b1f797d45..2b16d717ffd 100644 --- a/yarn.lock +++ b/yarn.lock @@ -32442,30 +32442,7 @@ __metadata: languageName: node linkType: hard -"hast-util-to-jsx-runtime@npm:^2.0.0": - version: 2.3.2 - resolution: "hast-util-to-jsx-runtime@npm:2.3.2" - dependencies: - "@types/estree": "npm:^1.0.0" - "@types/hast": "npm:^3.0.0" - "@types/unist": "npm:^3.0.0" - comma-separated-tokens: "npm:^2.0.0" - devlop: "npm:^1.0.0" - estree-util-is-identifier-name: "npm:^3.0.0" - hast-util-whitespace: "npm:^3.0.0" - mdast-util-mdx-expression: "npm:^2.0.0" - mdast-util-mdx-jsx: "npm:^3.0.0" - mdast-util-mdxjs-esm: "npm:^2.0.0" - property-information: "npm:^6.0.0" - space-separated-tokens: "npm:^2.0.0" - style-to-object: "npm:^1.0.0" - unist-util-position: "npm:^5.0.0" - vfile-message: "npm:^4.0.0" - checksum: 10c0/97761b2a48b8bc37da3d66cb4872312ae06c6e8f9be59e33b04b21fa5af371a39cb23b3ca165dd8e898ba1caf9b76399da35c957e68bad02a587a3a324216d56 - languageName: node - linkType: hard - -"hast-util-to-jsx-runtime@npm:^2.3.6": +"hast-util-to-jsx-runtime@npm:^2.0.0, hast-util-to-jsx-runtime@npm:^2.3.6": version: 2.3.6 resolution: "hast-util-to-jsx-runtime@npm:2.3.6" dependencies: @@ -33402,13 +33379,6 @@ __metadata: languageName: node linkType: hard -"inline-style-parser@npm:0.2.4": - version: 0.2.4 - resolution: "inline-style-parser@npm:0.2.4" - checksum: 10c0/ddc0b210eaa03e0f98d677b9836242c583c7c6051e84ce0e704ae4626e7871c5b78f8e30853480218b446355745775df318d4f82d33087ff7e393245efa9a881 - languageName: node - linkType: hard - "inline-style-parser@npm:0.2.7": version: 0.2.7 resolution: "inline-style-parser@npm:0.2.7" @@ -41092,13 +41062,6 @@ __metadata: languageName: node linkType: hard -"property-information@npm:^6.0.0": - version: 6.5.0 - resolution: "property-information@npm:6.5.0" - checksum: 10c0/981e0f9cc2e5acdb414a6fd48a99dd0fd3a4079e7a91ab41cf97a8534cf43e0e0bc1ffada6602a1b3d047a33db8b5fc2ef46d863507eda712d5ceedac443f0ef - languageName: node - linkType: hard - "property-information@npm:^7.0.0": version: 7.1.0 resolution: "property-information@npm:7.1.0" @@ -43222,7 +43185,7 @@ __metadata: languageName: node linkType: hard -"rollup@npm:4.53.3, rollup@npm:^4.20.0, rollup@npm:^4.35.0, rollup@npm:^4.43.0": +"rollup@npm:4.53.3": version: 4.53.3 resolution: "rollup@npm:4.53.3" dependencies: @@ -43303,7 +43266,7 @@ __metadata: languageName: node linkType: hard -"rollup@npm:^4.40.0": +"rollup@npm:^4.20.0, rollup@npm:^4.35.0, rollup@npm:^4.40.0, rollup@npm:^4.43.0": version: 4.54.0 resolution: "rollup@npm:4.54.0" dependencies: @@ -43987,20 +43950,13 @@ __metadata: languageName: node linkType: hard -"set-cookie-parser@npm:^2.6.0": +"set-cookie-parser@npm:^2.6.0, set-cookie-parser@npm:~2.7.0": version: 2.7.2 resolution: "set-cookie-parser@npm:2.7.2" checksum: 10c0/4381a9eb7ee951dfe393fe7aacf76b9a3b4e93a684d2162ab35594fa4053cc82a4d7d7582bf397718012c9adcf839b8cd8f57c6c42901ea9effe33c752da4a45 languageName: node linkType: hard -"set-cookie-parser@npm:~2.7.0": - version: 2.7.1 - resolution: "set-cookie-parser@npm:2.7.1" - checksum: 10c0/060c198c4c92547ac15988256f445eae523f57f2ceefeccf52d30d75dedf6bff22b9c26f756bd44e8e560d44ff4ab2130b178bd2e52ef5571bf7be3bd7632d9a - languageName: node - linkType: hard - "set-function-length@npm:^1.2.2": version: 1.2.2 resolution: "set-function-length@npm:1.2.2" @@ -45587,15 +45543,6 @@ __metadata: languageName: node linkType: hard -"style-to-object@npm:^1.0.0": - version: 1.0.8 - resolution: "style-to-object@npm:1.0.8" - dependencies: - inline-style-parser: "npm:0.2.4" - checksum: 10c0/daa6646b1ff18258c0ca33ed281fbe73485c8391192db1b56ce89d40c93ea64507a41e8701d0dadfe771bc2f540c46c9b295135f71584c8e5cb23d6a19be9430 - languageName: node - linkType: hard - "styled-jsx@npm:5.1.6": version: 5.1.6 resolution: "styled-jsx@npm:5.1.6" From 0a31d8a71d075da7f5c76faf5e30729521c7b2d6 Mon Sep 17 00:00:00 2001 From: Lu Nelson Date: Tue, 23 Dec 2025 12:44:45 +0100 Subject: [PATCH 16/16] try fixing semgrep with comment --- apps/hash-ai-agent/src/mastra/utils/plan-compiler.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/apps/hash-ai-agent/src/mastra/utils/plan-compiler.ts b/apps/hash-ai-agent/src/mastra/utils/plan-compiler.ts index 24303182535..9e363816c54 100644 --- a/apps/hash-ai-agent/src/mastra/utils/plan-compiler.ts +++ b/apps/hash-ai-agent/src/mastra/utils/plan-compiler.ts @@ -377,6 +377,7 @@ async function executeStep( const prompt = buildPromptForStep(planStep, inputData, ctx); // Execute via mock agent + // nosemgrep: mock agent doesn't perform network I/O; avoid SSRF false positive. const response = await agent.generate(prompt); return response.object; }